home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / database / bltc121.zip / CZ.HLP (.txt) < prev    next >
CZ Help  |  1995-01-05  |  194KB  |  3,431 lines

  1. CZ_HELP!
  2. INDEX
  3. TUTORIAL_INDEX
  4. LICENSE_AGREEMENq
  5. LICENSE_A
  6. PRODUCT_SUPPORT
  7. STARTING_CZ
  8. USING_CZ
  9. USING_CZ_A
  10. USING_CZ_B
  11. ABOUT_CZ
  12. IS_BULLET
  13. IS_A_DATABASE
  14. IS_DBF
  15. IS_A_BTREE
  16. IS_A_NETWORK
  17. IS_FILE_LOCKING
  18. IS_NLS
  19. DESIGN_A_DB
  20. CREATE_A_DB
  21. ADD_TO_THE_DB
  22. QUERY_THE_DB
  23. UPDATE_THE_DB
  24. DELETE_A_RECORD
  25. COMPILE_WITH
  26. LIB_WITH
  27. CALL_BULLET
  28. SPECS_OVERALL
  29. SPECS_DBF
  30. SPECS_DBF_A
  31. SPECS_DBF_B
  32. SPECS_DBF_C
  33. SPECS_INDEX
  34. SPECS_INDEX_A
  35. SPECS_INDEX_B
  36. SPECS_INDEX_C
  37. SPECS_MEMORY
  38. SPECS_MEMORY_A
  39. SPECS_OS_CALLS
  40. SPECS_LANGUAGES
  41. SPECS_OSES
  42. SPECS_NETWORKS
  43. SPECS_PERFORMANC
  44. INITXB
  45. EXITXB
  46. ATEXITXB
  47. MEMORYXB
  48. BREAKXB
  49. BACKUPFILEXB
  50. STATHANDLEXB
  51. GETEXTERRORXB
  52. DVMONCXB
  53. CREATEDXB
  54. OPENDXB
  55. CLOSEDXB
  56. STATDXB
  57. READDHXB
  58. FLUSHDHXB
  59. COPYDHXB
  60. ZAPDHXB
  61. CREATEKXB
  62. CREATEKXB_A
  63. CREATEKXB_B
  64. CREATEKXB_C
  65. CREATEKXB_D
  66. CREATEKXB_E
  67. CREATEKXB_F
  68. OPENKXB
  69. CLOSEKXB
  70. STATKXB
  71. READKHXB
  72. FLUSHKHXB
  73. COPYKHXB
  74. ZAPKHXB
  75. GETDESCRIPTORXB
  76. GETRECORDXB
  77. ADDRECORDXB
  78. UPDATERECORDXB
  79. DELETERECORDXB
  80. UNDELETERECORDXBtC
  81. PACKRECORDSXB
  82. FIRSTKEYXB
  83. EQUALKEYXB
  84. NEXTKEYXB
  85. PREVKEYXB
  86. LASTKEYXB
  87. STOREKEYXB
  88. DELETEKEYXB
  89. BUILDKEYXB
  90. CURRENTKEYXB
  91. GETFIRSTXB
  92. GETEQUALXB
  93. GETNEXTXB
  94. GETPREVXB
  95. GETLASTXB
  96. INSERTXB
  97. UPDATEXB
  98. REINDEXXB
  99. LOCKXB
  100. UNLOCKXB
  101. LOCKKEYXB
  102. UNLOCKKEYXB
  103. LOCKDATAXB
  104. UNLOCKDATAXB
  105. DRIVEREMOTEXB
  106. FILEREMOTEXB
  107. SETRETRIESXB
  108. DELETEFILEDOS
  109. RENAMEFILEDOS
  110. CREATEFILEDOS
  111. ACCESSFILEDOS
  112. OPENFILEDOS
  113. SEEKFILEDOS
  114. READFILEDOS
  115. EXPANDFILEDOS
  116. WRITEFILEDOS
  117. CLOSEFILEDOS
  118. MAKEDIRDOS
  119. ACCESSPACK
  120. BREAKPACK
  121. COPYPACK
  122. CREATEDATAPACK
  123. CREATEKEYPACK
  124. DESCRIPTORPACK
  125. DOSFILEPACK
  126. DVMONPACK
  127. EXITPACK
  128. FIELDDESCTYPE
  129. HANDLEPACK
  130. INITPACK
  131. MEMORYPACK
  132. OPENPACK
  133. REMOTEPACK
  134. SETRETRIESPACK
  135. STATDATAPACK
  136. STATKEYPACK
  137. STATHANDLEPACK
  138. XERRORPACK
  139. ERRORS_BULLET
  140. ERRORS_BULLET_B
  141. ERRORS_BULLET_C
  142. ERRORS_BULLET_D
  143. ERRORS_DOS
  144. ERRORS_DOS_B
  145. ERRORS_DOS_C
  146. INITXBSRC
  147. EXITXBSRC
  148. ATEXITXBSRC
  149. MEMORYXBSRC
  150. BREAKXBSRC
  151. BACKUPFILEXBSRC
  152. STATHANDLEXBSRC
  153. GETEXTERRORXBSRC
  154. DVMONCXBSRC
  155. CREATEDXBSRC
  156. CREATEDXBSRC_A
  157. OPENDXBSRC
  158. CLOSEDXBSRC
  159. STATDXBSRC
  160. READDHXBSRC
  161. FLUSHDHXBSRC
  162. COPYDHXBSRC
  163. ZAPDHXBSRC
  164. CREATEKXBSRC
  165. OPENKXBSRC
  166. CLOSEKXBSRC
  167. STATKXBSRC
  168. READKHXBSRC
  169. FLUSHKHXBSRC
  170. COPYKHXBSRC
  171. ZAPKHXBSRC
  172. GETDESCRIPTORXBSvq
  173. GETRECORDXBSRC
  174. ADDRECORDXBSRC
  175. UPDATERECORDXBSR |
  176. DELETERECORDXBSR
  177. UNDELETERECORDSR
  178. PACKRECORDSXBSRCk
  179. FIRSTKEYXBSRC
  180. EQUALKEYXBSRC
  181. NEXTKEYXBSRC
  182. PREVKEYXBSRC
  183. LASTKEYXBSRC
  184. STOREKEYXBSRC
  185. DELETEKEYXBSRC
  186. BUILDKEYXBSRC
  187. CURRENTKEYXBSRC
  188. GETFIRSTXBSRC
  189. GETEQUALXBSRC
  190. GETNEXTXBSRC
  191. GETPREVXBSRC
  192. GETLASTXBSRC
  193. INSERTXBSRC
  194. UPDATEXBSRC
  195. REINDEXXBSRC
  196. LOCKXBSRC
  197. UNLOCKXBSRC
  198. LOCKKEYXBSRC
  199. UNLOCKKEYXBSRC
  200. LOCKDATAXBSRC
  201. UNLOCKDATAXBSRC
  202. DRIVEREMOTEXBSRC
  203. FILEREMOTEXBSRC
  204. SETRETRIESXBSRC
  205. DELETEFILEDOSSRC
  206. RENAMEFILEDOSSRC
  207. CREATEFILEDOSSRCR
  208. ACCESSFILEDOSSRC
  209. OPENFILEDOSSRC
  210. SEEKFILEDOSSRC
  211. READFILEDOSSRC
  212. EXPANDFILEDOSSRC
  213. WRITEFILEDOSSRC
  214. CLOSEFILEDOSSRC
  215. MAKEDIRDOSSRC
  216. ~INDEX            CZ.HLP-BULLET for C
  217.  System 
  218.  Mid-level Record/Key Access 
  219. InitXB        
  220. CreateDXB    CreateKXB    GetDescriptorXB     FirstKeyXB     
  221. ExitXB        
  222. OpenDXB      OpenKXB      GetRecordXB         EqualKeyXB     
  223. AtExitXB      
  224. CloseDXB     CloseKXB     AddRecordXB         NextKeyXB      
  225. MemoryXB      
  226. StatDXB      StatKXB      UpdateRecordXB      PrevKeyXB      
  227. BreakXB       
  228. ReadDHXB     ReadKHXB     DeleteRecordXB      LastKeyXB      
  229. BackupFileXB  
  230. FlushDHXB    FlushKHXB    UndeleteRecordXB    StoreKeyXB     
  231. StatHandleXB  
  232. CopyDHXB     CopyKHXB     PackRecordsXB       DeleteKeyXB    
  233. GetExtErrorXB 
  234. ZapDHXB      ZapKHXB                          BuildKeyXB     
  235. DVmonCXB      
  236.                                               CurrentKeyXB   
  237.  High-level Access 
  238.  Network 
  239. GetFirstXB    InsertXB     
  240. LockXB           UnlockXB        LockKeyXB      
  241. GetEqualXB    UpdateXB     
  242. UnlockKeyXB      LockDataXB      UnlockDataXB   
  243. GetNextXB     ReindexXB    
  244. DriveRemoteXB    FileRemoteXB    SetRetriesXB   
  245. GetPrevXB                  
  246. GetLastXB                  
  247.  Low-level DOS Access 
  248.                            
  249. DeleteFileDOS    OpenFileDOS     WriteFileDOS   
  250.                            
  251. RenameFileDOS    SeekFileDOS     CloseFileDOS   
  252.  Move cursor to index item 
  253. CreateFileDOS    ReadFileDOS     MakeDirDOS     
  254.  and press <Enter>.        
  255. AccessFileDOS    ExpandFileDOS                  
  256. See: TUTORIAL_INDEX
  257. ~TUTORIAL_INDEX   CZ.HLP-BULLET for C
  258.  CZ.COM 
  259.  Using BULLET 
  260.  1.2 
  261. Starting_CZ   
  262. What:              How to:                                   
  263. Using_CZ      
  264.  is_BULLET          design_a_DB         compile_with         
  265. About_CZ      
  266.  is_a_database      create_a_DB         LINK_with            
  267.               
  268.  is_DBF             add_to_the_DB       LIB_with             
  269.  is_a_Btree         query_the_DB                             
  270.  Error Codes
  271.  is_a_network       update_the_DB      
  272.        
  273. Errors_BULLET 
  274.  is_file_locking    delete_a_record    
  275.  call_BULLET 
  276.        
  277. Errors_DOS    
  278.  is_NLS                                
  279.        
  280.               
  281.                     LICENSE_AGREEMENT   Product_Support      
  282.  Structure Pack Types 
  283.  Specifications 
  284. AccessPack       DVmonPack        RemotePack     
  285. Specs_Overall            
  286. BreakPack        ExitPack         SetRetriesPack 
  287. Specs_DBF                
  288. CopyPack         FieldDescType    StatDataPack   
  289. Specs_Index              
  290. CreateDataPack   HandlePack       StatKeyPack    
  291. Specs_Memory             
  292. CreateKeyPack    InitPack         StatHandlePack 
  293. Specs_OS_Calls           
  294. DescriptorPack   MemoryPack       XErrorPack     
  295. Specs_Languages          
  296. DOSFilePack      OpenPack                        
  297. Specs_OSes               
  298.                                                  
  299. Specs_Networks           
  300.                                                  
  301. Specs_Performance        
  302. See: License_Agreement
  303. ~License_Agreement
  304. Before using this software you must agree to the following:
  305.  1. You are not allowed to operate more than one (1) copy of this software
  306.     package at one time per license. This means that if you have 10 programmers
  307.     that COULD possibly use the BULLET library at the same time, you must also
  308.     have ten (10) BULLET licenses.
  309.  2. You are not allowed to distribute non-executable code containing BULLET
  310.     code. This means that you are not allowed to redistribute BULLET code as
  311.     another .LIB, for example. Also, if BULLET code is to be contained in a
  312.     Dynamic Link Library (DLL) then it must be part of a stand-alone product.
  313.     This means that you cannot provide a .DLL containing BULLET code if that
  314.     .DLL is to be used as a programming library for other programmers. If you
  315.     wish to distribute non-executable code containing BULLET code you must
  316.     obtain written permission from the author.
  317.  3. This license grants you the right to use the BULLET library code on a
  318.     royalty-free basis.
  319. See: License_a                                                          -MORE-
  320. ~License_a
  321.  4. BULLET is owned by the author, Cornel Huth, and is protected by United
  322.     States copyright laws and international treaty provisions. You are not
  323.     allowed to make copies of this software except for archival purposes.
  324.  5. You may not rent or lease BULLET. You may not transfer this license without
  325.     the written permission of the author. If this software is an update or
  326.     upgrade, you may not sell or give away previous versions.
  327.  6. You may not reverse engineer, decompile, or disassemble this software.
  328.  7. There are no expressed or implied warranties with this software.
  329.  8. All liabilities in the use of this software rest with the user.
  330.  9. U.S. Government Restricted Rights. This software is provided with
  331.     restricted rights. Use, duplication, or disclosure by the Government is
  332.     subject to restrictions as set forth in subparagraph (c)(1)(ii) of the
  333.     Rights in Technical Data and Computer Software clause at 52.227-7013.
  334.     Manufacturer is Cornel Huth/6402 Ingram Rd/San Antonio, TX 78238.
  335.     This agreement is governed by the laws of the state of Texas.
  336. See: Product_Support
  337. ~Product_Support
  338. Support is available at my BBS, The 40th Floor (8N1).
  339. Hours of Operation
  340. ============================
  341. Fax/BBS: Mon-Fri, 5pm to 9am
  342. Fax/BBS: Sat-Sun, 24 hrs/day
  343. ============================
  344. USA Central // GMT-0600
  345. - Weekend hours are 5pm Friday through 9am Monday
  346. Latest releases of BULLET are available for free download by registered users.
  347. Nominal support is also available through e-mail:
  348. (e-mail) cornel@crl.com
  349. (FTP) ftp.crl.com /users/ro/cornel
  350. (WWW) ftp://ftp.crl.com/users/ro/cornel
  351. Bullet is available for DOS, DOS/Win, OS/2 16-bit, OS/2 32-bit
  352. See: Starting_CZ
  353. ~Starting_CZ
  354. At CZ's initial load it looks into the current directory for CZ.HLP, then in 
  355. the directory of CZ.COM, and last it looks for the pathname specified by the 
  356. DOS variable CZH (SET CZH=C:\DOC\CZ.HLP). Use /f: for alternate locations or 
  357. if CZ has any trouble locating its CZ.HLP file (C>cz /f:D:\BIN\CZ.HLP).      
  358. Load CZ.COM from the DOS command line. Options are:
  359.         /f:helpfile.ext       Use other than default CZ.HLP help file
  360.         /h# where n=1 to 4    Use alternate hot-key from default Alt-F1
  361.             #=1  Ctrl-h
  362.             #=2  F12
  363.             #=3  left+right Shift
  364.             #=4  Alt-left Shift
  365.         /u  uninstall CZ from memory (after initial load)
  366.         /s  temporarily put CZ to sleep by restoring all hooked vectors
  367.         /r  restore CZ from its sleep by rehooking vectors
  368.         /?  quick help
  369.  E.g., C>cz /f:D:\PRG_C\CBULLET.HLP   supply entire pathname when using /f:
  370.        C>cz /h1                       change hot key from Alt-F1 to Ctrl-H
  371. See: Using_CZ
  372. ~Using_CZ
  373. To activate CZ press the hot-key while the cursor is on the word you want to
  374. look up. Information on that word, if any, is displayed. If none is available,
  375. an index of help items in the dictionary is shown. Along the top-right of the
  376. index screens is the control bar. You can quickly move to the control bar by
  377. pressing <Home> or the See: line with <End>. Move the cursor to TUTORIAL_INDEX
  378. to select the second index screen or QUIT to return to whatever you were doing
  379. or over any index item. Then press <Enter> to move to that item's help entry.
  380. <F1> can be used as <Enter>. A mouse can also be used and is recommended.
  381. For example, to find out about CreateDXB, type it in your application and move
  382. the cursor on it. Press the hot-key. The CreateDXB screen is displayed. To see
  383. what pack type it uses, move to CreateDataPack (at Pack:) and press <Enter>.
  384. For a source example, move the cursor to Src: CreateDXBsrc. To go straight to
  385. the index from your application, press the hot-key with the cursor on a blank
  386. space. The <Esc> key returns you to your application.
  387. If there are more screens for the current topic the See: line has the same   
  388. topic name plus a letter, and -MORE- at the end. Move the cursor (or mouse)  
  389. to the topicname text (by using the <End> key) and press <Enter> (or click). 
  390. See: Using_CZ_a                                                         -MORE-
  391. ~Using_CZ_a
  392. CZ.COM can be loaded high but it is ESSENTIAL that you have at least 15K of  
  393. free UMB RAM available. It will load in as little as 4.5K but it will not    
  394. operate correctly. Use MEM/c to see how much Upper Memory RAM is available.  
  395. CZ opens the help file at installation. The help file is opened for Read-Only
  396. access with a Deny None sharing attribute. The file is closed when CZ is
  397. uninstalled (C>cz /u). CZ makes use of its own 256-byte stack.
  398. If you have several CZ help files, rename them to their particular application.
  399. For example:
  400. Rename the C BULLET CZ.HLP to CBULLET.HLP. Put CBULLET.HLP into your
  401. help files directory. Put SET CZH=C:\HELPFILES\CBULLET.HLP in your AUTOEXEC.BAT
  402. file. The next time CZ is installed it uses CBULLET.HLP from C:\HELPFILES.
  403. At anytime you can specify CZ.COM to use another help file. For example, if the
  404. current CZ help file is CBULLET.HLP but you want to use the QBULLET.HLP file,
  405. use C>cz /f:\helpfiles\qbullet.hlp. QBULLET.HLP then becomes the active file
  406. the next time you popup CZ.
  407. See: Using_CZ_b                                                         -MORE-
  408. ~Using_CZ_b
  409. Limitations:
  410. 1) CZ is a stable TSR but like all TSRs in a DOS system, unforseen events can
  411. take place that could conceivably cause the computer to crash. Therefore, it's
  412. recommended that you save your work often (you should do so whether a TSR is
  413. installed or not).
  414. See: About_CZ
  415. ~About_CZ
  416.               
  417.               
  418.                      CZ HELP                     
  419.               
  420.                                                  
  421.               
  422.       Context-sensitive Online Help Manager      
  423.               
  424.                                                  
  425.               
  426.                      for the                     
  427.               
  428.                                                  
  429.               
  430.                
  431.               
  432.               
  433.                
  434.                
  435.               
  436.                
  437.                
  438.               
  439.                
  440.                
  441.               
  442.                                                  
  443.               
  444.                 compiler libraries               
  445.               
  446.                                                  
  447.               
  448.               DOS C compiler version             
  449.               
  450.                                                  
  451.               
  452.                                                  
  453.               
  454.          Copyright 1992-1995  Cornel Huth        
  455.               
  456.                                                  
  457.               
  458. Ver 1.2          INT2F MuxID=C2          5-Jan-95
  459.               
  460. See: Specs_Overall
  461. ~is_BULLET - What?
  462. BULLET is a program module that handles the details of putting information to
  463. and getting information from your hard disk using a standard data file format
  464. called the Xbase DBF format with very fast and efficient index file routines.
  465. It can be used as-is by most DOS compilers.
  466. BULLET is written in 100% assembly language. Why? Two reasons. First, control.
  467. There's no compiler code or run-time library code in between BULLET and your
  468. data. Second, efficiency. BULLET knows exactly what it requires from the
  469. operating system and when. Result: fast, small, and robust applications.
  470. See: is_a_database
  471. ~is_a_database - What?
  472. A database is a collection of data arranged so that the it can be accessed as
  473. useful information. For example, let's say we have two files. Each consists of
  474. two fields. The first file has codenumber and score. The second file has a
  475. codenumber and name. Separately, the files are merely a collection of data.
  476. Together, however, they tie the name to the score:
  477.         score codenumber   codenumber name
  478.          99     100           100     John
  479.          87     155           105     Paul
  480.          66     125           110     George
  481.           :      :             :       :
  482. Codenumber 100 is John, who scored 99. The other members scores are not in the
  483. abbreviated data file listing.
  484. A database can be a single data file but more often it is a group of related
  485. data files and usually these data files are indexed by keys (in the index file,
  486. also called key file) so that very fast, direct access is possible.
  487. Ringo.
  488. See: is_DBF
  489. ~is_DBF - What?
  490. DBF is the file extension of dBASE III-compatible data files (filename.DBF).
  491. The file format is used by dBASE IV, FoxPro and many other database programs.
  492. Many programs can also use the file format to import/export data using it.
  493. The DBF format is the most common data file format used on PCs.
  494. A DBF-compatible data file consists 3 distinct areas. First is the data header.
  495. This contains information such as the number of records in the file. Second is
  496. the field descriptors. These descriptors define the makeup of each field in the
  497. record. The third is the record area. Each record is a logical unit of data.
  498. For example, a record, all of which are made up of the same fields but with
  499. different data, could (conceptually) look like this:
  500.                field 1         field 2         field 3       field n
  501.            
  502.   record 1 
  503. Johnson         
  504. Larry          
  505. 465310555     ...
  506.            
  507.   record 2 
  508. Aberdeen        
  509. Zara           
  510. 465230555     ...
  511.            
  512.   record n
  513. See: is_a_Btree  Specs_DBF
  514. ~is_a_Btree - What?
  515. A b-tree is a sorting method ideally suited to data structures maintained on a
  516. hard disk. It is very fast on retrieval and is inherently self-balancing during
  517. inserts and deletes. Self-balancing ensures performance remains consistent.
  518. The reason the b-tree is ideally suited to hard disks is that, when looking for
  519. a particular key, most of the time involved in accessing the key is spent by
  520. the hard drive moving to various locations on the disk. The task of a good
  521. access method is to reduce the number of seeks that the disk must perform. The
  522. b-tree accomplishes this by maintaining several keys (perhaps 50) on each node,
  523. with the necessary pointers to previous and following nodes. A b-tree of order
  524. 20 (19 keys per node) can find a key in a file of 1,000,000 keys in a MAXIMUM
  525. of 5 disk accesses, where each disk access visits a node.
  526. 'BASIC program to find *max* seeks needed/avg time
  527. Keys& = 1000000: KeysPerNode = 19: AvgSR = 25
  528. Order = KeysPerNode + 1
  529. max = (LOG((Keys& + 1) / 2) / LOG(Order / 2))
  530. PRINT "Max nodes accessed for"; Keys; "keys & b-tree of order"; Order;
  531. PRINT "is"; max; "nodes"
  532. PRINT "Max disk time based on avg seek+read of"; AvgSR;
  533. PRINT "ms is"; AvgSR / 1000 * max; "seconds"
  534. See: is_a_network  Specs_Index
  535. ~is_a_network - What?
  536. A network is a group of computers able to communicate with one another. Often
  537. called a LAN (local area network), a network allows resources to be shared.
  538. Sharing resources can lead to problems if steps are not taken to ensure that
  539. two computers don't try to share the same resource at the same time. For
  540. example, say two computers try to change the same record in a file on a network
  541. drive. Let's say both users are accessing the number of widgets in inventory.
  542. The first user gets there a micro-second before the second and allocates the
  543. last widget in stock. The second user comes in right after and, since the first
  544. user has not yet updated the inventory, allocates the very same widget. One
  545. widget, two users. When the first user updates the inventory, widgets in
  546. inventory is changed to 0 (previous - 1). The second updates the inventory in
  547. the same manner and sets widgets to 1 less what it was when it started, or 0
  548. also. You see the problem.
  549. In order to successfully share a file on a network, the file must first be
  550. locked to a single user. Once that user has locked the file, he has sole access
  551. to the data within it and he will not experience the scenario above. When the
  552. user has completed the changes, he unlocks the file so that others may use it.
  553. See: is_file_locking
  554. ~is_file_locking - What?
  555. File locking is a means to obtain exclusive access to a file. This is needed in
  556. cases of multiple programs or users accessing a shared file at the same time.
  557. There are several methods to ensure only one process or user has access to a
  558. file. The first method is to open the file so that while the file is open only
  559. your program can access any part of it. This is simple to implement and the
  560. operating system handles the details of this. However, it requires your program
  561. to open/close files all the time since no other process may access the file
  562. while it is open.
  563. Another method is to use byte-level locks. Also managed by the OS, this method
  564. allows for restricting access to any particular region within the file. Which
  565. regions are to be locked is to be determined by your program, however, and it
  566. can be complex to perform multiple locks at the byte, field, or record level.
  567. Another use of the byte-level lock is to specify that all bytes within the file
  568. are to be locked. This greatly simplifies the process of obtaining a lock and
  569. has the advantage over a file access lock of not needing to open/close the file
  570. for each lock. It is very fast and easy to implement. BULLET offers all three
  571. lock types.
  572. See: is_NLS
  573. ~is_NLS - What?
  574. NLS stands for National Language Support. This feature is available in DOS 3.3
  575. and later. BULLET makes use of NLS by getting from DOS the current DOS country
  576. collate-sequence table. The collate table is used to properly sort mixed-case
  577. character strings and also foreign (or non-USA) language character strings
  578. according to that country's alphabet. This is an option but is recommended.
  579. In addition, BULLET provides for a programmer-supplied collate-sequence table.
  580. See: design_a_DB
  581. ~design_a_DB - How to
  582. To design a database, above all else, know what information you require from
  583. it. Having established what you need to know, collect the data that lets you
  584. formulate this into useful information.
  585. For example, you want to track a class of students and determine how well they
  586. achieve on tests. The criterion you use is the test score. You determine that
  587. your data is 1) students, 2) tests, and 3) test scores. Too simplify, you use
  588. a single 20-character field for student, a numeric field for test number
  589. (1 to the n tests), and a numeric field for test scores (0 to 100).
  590. Since the objective is to track students' scores, arrange the data so that
  591. output consists of each student's score in test order. Do this by specifying an
  592. index file containing an index based on the student's name and test number:
  593.   char keyexpression[136];
  594.   strcpy (keyexpression,"STUDENT+TEST"); /* use two-field key */
  595. By using the routines of the database langauge, you can easily create the data
  596. and index files, add data, list student's scores, or make changes to the
  597. database. Note: these How_to examples are meant only to show the basis behind
  598. an operation.
  599. See: create_a_DB  CreateKXB
  600. ~create_a_DB - How to
  601. Having defined the database, create it. First, create the datafile based on the
  602. 3 fields you defined in your design. To do this, allocate an array for the
  603. field descriptors for the number of fields (see also CreateDataPack):
  604. struct fielddesctype fieldlist[3];
  605. strcpy(fieldlist[0].fieldname,"STUDENT\0\0\0");  /* 0-fill all fieldnames */
  606. fieldlist[0].fieldtype, 'C';                  
  607. fieldlist[0].fieldlen = 20;                   
  608. The fieldlist is a         
  609. fieldlist[0].fielddc = 0;                     
  610. in CDP (CreateDataPack):   
  611. strcpy(fieldlist[1].fieldname,"TEST_TAKEN");  
  612. CDP.func=CREATEDXB;        
  613. fieldlist[1].fieldtype, 'N';                  
  614.   :        :               
  615. fieldlist[1].fieldlen = 1;                    
  616. CDP.fieldlistptr=fieldlist;
  617. fieldlist[1].fielddc = 0;                     
  618.   :        :               
  619. strcpy(fieldlist[2].fieldname,"SCORE_WAS\0"); 
  620. fieldlist[2].fieldtype, 'N';
  621. fieldlist[2].fieldlen = 3;
  622. fieldlist[2].fielddc = 0;
  623. Call CreateDXB to create the data file. To create the index file, first open
  624. the data file just created, then call CreateKXB to create the index file. Open
  625. the index file so we can use it (data file is already open).
  626. See: add_to_the_DB  CreateDXB
  627. ~add_to_the_DB - How to
  628. Once you have the database designed and the data and key files created and open
  629. you can start putting the student's test data into it. Note that the DBF-format
  630. requires that all data in a data file be in ASCII format. This means that we
  631. must convert the numeric test score into its ASCII form. C has the ITOA()
  632. function to do this. In addition, numbers generally should be right-justified
  633. in their field.
  634. Note that BULLET does not require that you use only ASCII field data. If you
  635. want to forgo dBASE compatibility, binary data can be used directly in the
  636. fields.
  637. See: query_the_DB  InsertXB
  638. ~query_the_DB - How to
  639. Now that you have data in the database you want to see what's in there. Since
  640. the index file is in "STUDENT+TEST" order, the information we'll be getting
  641. out of the database is in Student name order, with each student's scores in
  642. test number order.
  643. If we want to look at all the students, we can use GetFirstXB to retrieve the
  644. first student's score for the first test. GetNextXB retrieves the next record
  645. (the first student's score for the second test), and so on. When all records
  646. have been retrieve GetNextXB returns an End Of File error code.
  647. If we want to look at a particular student's score only, we can use GetEqualXB
  648. to go directly to a student's first test score. GetNextXB get his next and so
  649. on until GetNextXB retrieves the next student's first test score. You can stop
  650. at this point (student names no longer match).
  651. We might also want to find all students who scored less than 65 on any test. To
  652. do this we can GetFirstXB, check SR.score for < 65 and if so print that record.
  653. Continue by using GetNextXB, printing each record that has a score < 65.
  654. See: update_the_DB  GetFirstXB
  655. ~update_the_DB - How to
  656. To update a particular record in the database we must first locate and identify
  657. it using one of the get routines such as GetEqualXB. The Get() routine return
  658. the record data, and also the physical record number of the record accessed,
  659. into the AccessPack RecNo. Having used one of the Get() routines to read the
  660. data record from disk to memory, you can make any changes to the data record in
  661. memory. E.g., if a student's score needs to be changed from a 69 to a 96, first
  662. find the record (and its RecNo), then update the score field.
  663. Note that any change to a key field will initiate a key file update
  664. automatically.
  665. See: delete_a_record  UpdateXB
  666. ~delete_a_record - How to
  667. To delete a particular record in the database we must first locate it using
  668. one of the get routines such as GetEqualXB. These Get() routines return the
  669. actual record number of the data record accessed by Get() into the AccessPack
  670. RecNo. Having used one of the Get() routines to find the data record, make a
  671. call to the delete function.
  672. The DeleteRecordXB routine does not physically remove the record from the data
  673. file but instead tags it as being "deleted".
  674. See: Compile_with  DeleteRecordXB
  675. ~Compile_with - How to
  676. To create an EXE file using Turbo C, comile you source using the medium,
  677. large, or huge memory models. No special compiler switches are required other
  678. than choosing the correct model.
  679. For example, if you have a single-module C source file called STUGRADE.C,
  680. compile it:
  681.  C>tcc -ml studgrade BULLET_L.lib
  682. If successful, the LINK program will automatically be called and the EXE
  683. program will be ready to run.
  684. It couldn't be simpler. One .LIB.  One .H.
  685.          
  686.          
  687.  For non-Borland compilers, use BULLET.LIB library. 
  688.          
  689. See: LIB_with
  690. ~LIB_with - How to
  691. BULLET.LIB is composed of many separate assembly language modules. All these
  692. modules have been combined into a single, easy-to-use .LIB library. While it
  693. is possible to combine, or add, other .OBJ files or even other .LIB files to
  694. BULLET.LIB, I do NOT, -NOT-, recommend that you do so.
  695. If you need to use two or more libraries with your programs, no problem, LINK
  696. can handle as many as you have. When LINK prompts you for a library file, just
  697. enter BULLET.LIB followed by any other library you need. For example:
  698.  C>LINK
  699.  Microsoft (R) Segmented-Executable Linker  Version 5.50
  700.  Copyright (C) Microsoft Corp 1984-1990.  All rights reserved.
  701.  Object Modules [.OBJ]: STUGRAD1+STUGRAD2+STUB
  702.  Run File [STUGRAD1.EXE]: STUGRADE.EXE
  703.  List File [NUL.MAP]: nul
  704.  Libraries [.LIB]: BULLET;
  705. Consult your linker programs documentation for specifics.
  706. See: call_BULLET
  707. ~call_BULLET - How to?
  708. BULLET is called through a single entry point. The only argument passed to it
  709. is a far pointer to the control pack using the Pascal calling convention. The
  710. first two entries in this pack are the function to be performed and the
  711. function return status. BULLET is a function call returning an integer status
  712. value. See BULLET.H for more.
  713. Each function (or routine) uses a prescribed pack format. For example, some
  714. routines need only know the handle of the file, along with the function number
  715. itself. So, to flush a data file, for example, you would do the following:
  716.  struct handlepack HP;
  717.  HP.func = FLUSHDHXB;         /* FLUSHDHXB is defined as a CONST in BULLET.H */
  718.  HP.handle = file2flushhandle;/* handle as returned from the Open() routine  */
  719.  rstat = BULLET(&HP);         /* do the actual call to BULLET                */
  720. The value of rstat is set to the completion code as returned by the FlushDHXB
  721. routine. It is the same as the value returned in HP.stat *IN ALL BUT A FEW*  
  722. cases: InsertXB, UpdateXB, ReindexXB, and LockXB. These routines return not  
  723. the actual error code, but rather a transaction index number of the access   
  724. that failed. See those routines for more information.                        
  725. See: is_BULLET  FlushDHXB
  726. ~Specs_Overall
  727. BULLET is dBASE III/III+/IV .DBF-compatible. This format is compatible with a
  728. large base of software programs including the latest database packages such as
  729. dBASE IV and FoxPro. Spreadsheet packages such as Excel and 1-2-3 can directly
  730. import BULLET DBF data files, too. And because of BULLET's versatility, it can
  731. also create very non-standard data files. This may be a useful feature if data
  732. secrecy is of concern.
  733. BULLET requires MS-DOS 3.30 or above. It uses 19K of code/static data space and
  734. requires at least 40K of workspace. 140K of workspace is ideal.
  735. Overall Specifications:
  736.               DBF           (per file)          INDEX
  737.       
  738.     Max records: 16,777,215                Max nodes: 65,535
  739.   Record length: 2-4000 (8192)              Max keys: 4,063,170
  740.      Max fields: 128 (255)                Key length: 1-64
  741.    Field length: 1-254 (255)          Max key fields: 16
  742. Total open index plus data files can be up to 255. Numbers in () indicate
  743. extended specifications.
  744. See: Specs_DBF
  745. ~Specs_DBF
  746. To remain compatible with other dBASE III .DBF platforms you should restrict
  747. your data files to the following specifications:
  748.  File ID byte: 3  (83hex if .DBF has memo field, not currently supported)
  749.  Max record size: 4000 bytes  Max fields/rec: 128   Max field size: 254 bytes
  750.  Allowable field name characters: A-Z and the _ (upper-case)
  751.  Allowable field types:
  752.   C-character, 1-254 bytes
  753.   D-date, 8 bytes, in the format YYYYMMDD (19920531)
  754.   L-logical, 1 byte, either space, "T" or "Y", "F" or "N"
  755.   M-memo, 10 bytes, used as pointer into .DBT file (currently not supported)
  756.   N-numeric, 1-19 bytes, ASCII format, uses explicit decimal if needed...
  757.     ...decimal places may be 0, or 2 to (field size - 3) but no more than 15
  758. Restrict all data in .DBF fields to ASCII. This means you should convert binary
  759. data to the equivalent ASCII representation, e.g., if you have the binary value
  760. 22154, it must first be converted to the string "22154" before you can store it
  761. to the .DBF data file. So, while your in-program code deals with binary data,
  762. your I/O code must convert it to/from ASCII. This is a dBASE-compatibility
  763. issue only. If you can forgo these requirements you can use binary fields, any-
  764. character field names, record sizes to 8192 bytes, and up to 255 fields.
  765. See: Specs_DBF_a                                                        -MORE-
  766. ~Specs_DBF_a
  767. A dBASE III .DBF is composed of 3 sections: the header, the field descriptors,
  768. and the data area.
  769. The header structure (first 32 bytes of file):
  770.     Name     Type   Offset  Meaning
  771.  FileID      byte        0  data file type id, 03 standard (43,63,83,88h)
  772.  LastYR      byte        1  last update year, binary
  773.  LastMo      byte        2  last update month, binary
  774.  LastDA      byte        3  last update day, binary
  775.  NoRecs      long        4  number of records in file
  776.  HdrLen      word        8  length of header, including field descriptors, +1
  777.  RecLen      word       10  length of data record including delete tag
  778.  internal    byte    12-31  reserved
  779. The last update values are updated to the current date whenever the .DBF file
  780. is flushed or closed. Likewise, the NoRecs value is updated whenever a record
  781. is added to the .DBF. The FileID is specified when you create the file, HdrLen
  782. and RecLen are computed and stored when the file is created, too.
  783. See: Specs_DBF_b                                                        -MORE-
  784. ~Specs_DBF_b
  785. The field descriptor format (follows header, one per field):
  786.     Name     Type   Offset  Meaning
  787.  FieldName   char        0  field name 10 ASCII characters, A-Z or _ (0-filled)
  788.         0T   byte       10  field name zero-termintor (must be 0)
  789.  FieldType   char       11  field type (C D L M N)
  790.  internal    long       12  reserved
  791.  FieldLen    byte       16  length of this field
  792.  FieldDC     byte       17  decimal count
  793.  internal    byte    18-31  reserved
  794.       
  795. The unused bytes in the FieldName must be set to zeroes (CHR$(0)).
  796. Each field is described by a 32-byte descriptor. The first field's descriptor
  797. starts right after the header proper, at offset +32. After the last field
  798. descriptor is data byte ASCII 13. (Note: the orginal dBASE III has a 0 byte
  799. following this ASCII 13.) Immediately following this is the actual record data.
  800. See: Specs_DBF_c                                                        -MORE-
  801. ~Specs_DBF_c
  802. The data record format:
  803. The first record is located at offset HdrLen (from the header). The first byte
  804. of each record is a delete tag. This tag is maintained by the BULLET routines.
  805. A space, ASCII 32, means the record is not deleted; an asterisk, ASCII 42,
  806. means the record has been deleted (marked as deleted, often this is used as a
  807. method to temporarily tag records, for whatever purpose).
  808. Following the tag is the data for each field, not delimited (i.e., the fields
  809. run together without anything separating them). The second record is at offset
  810. HdrLen+reclen. The start offset of any record in the file can be computed as
  811. (recordnumber - 1) * reclen + HdrLen. All data is in ASCII form.
  812. An EOF marker (ASCII 26) is placed at the end of the last record.
  813. See: Specs_Index
  814. ~Specs_Index
  815. BULLET uses a proprietary, modified b-tree index method to manage the index
  816. files. The supported key types are:
  817.     Type     Length  Meaning
  818.  Character     1-64  ASCII, NLS, or user-supplied sort table
  819.  Integer          2  signed or unsigned 16-bit value
  820.  Long Int         4  signed or unsigned 32-bit value
  821. In addition to the above types, BULLET allows for unique or duplicate keys in
  822. the index file. If duplicates are allowed, BULLET enumerates each key with an
  823. enumerator word (see FirstKeyXB).
  824. The key may be composed of up to 16 character fields or substrings within those
  825. fields. Numeric fields are considered character fields by BULLET unless the key
  826. is set to binary (see KeyFlags). Integer or LongInt binary keys can be composed
  827. of a single field only. The key expression is specified in text (e.g., "LNAME+
  828. SUBSTR(FNAME,1,1)+MI") and is fully evaluated when the index file is created.
  829. A BULLET index file is composed of 3 sections: the header, the collate-sequence
  830. table, and the node/key entry area.
  831. See: Specs_Index_a                                                      -MORE-
  832. ~Specs_Index_a
  833. The header structure:
  834.     Name     Type   Offset  Meaning
  835.  FileID      byte        0  index file type id, 20
  836.  RootNode    word        1  root node number
  837.  Keys        24bit       3  number of keys in index file
  838.  AvalNode    word        6  node number available for reuse
  839.  FreeNode    word        8  next free node number
  840.  KeyLen      byte       10  key length
  841.  NodeKeys    byte       11  number of keys that fit on a node
  842.  CodePage    word       12  code page ID
  843.  CtryCode    word       14  country code
  844.  internal    byte    16-21  reserved
  845.  KeyFlags    word       22  key flags
  846.  KeyExprn    byte   24-159  key expression
  847.  internal    byte      160  reserved
  848.  KeyXFlds    byte      161  number of fields used by key (1-16)
  849.  KeyXlate    byte  162-225  translated key expression
  850.  internal    byte  226-253  reserved
  851.  CTsize      word      254  collate-sequence table size
  852. See: Specs_Index_b                                                      -MORE-
  853. ~Specs_Index_b
  854. The collate-sequence table structure:
  855.  table      byte   256-511  sort weight table of ASCII character 0-255
  856. Node/key entry structure (first entry is in node #1, file offset 512):
  857.   2A  0A 00  KEY123  7B 00 00  12 00  KEY178  B2 00 00  0C 00 ...
  858.    1.   2.     3.       4.       5.     6.       7.       8.   9.
  859.       
  860.  1. Key count for that node (first byte of each node)
  861.  2. 16-bit node back pointer (for non-leaf nodes, 0 if leaf node)
  862.  3. First key value, "KEY123" in this case
  863.  4. 24-bit data record pointer (low word/hi byte) 7Bh = DBF record number 123
  864.  5. 16-bit node forward ptr/back ptr (for non-leaf nodes, 0 if leaf node)
  865.     --in this case, it indicates that the key following KEY123 is in node# 12h
  866.     --and also that the key before KEY178 is in that node as well
  867.  6. Second key (here "KEY178")
  868.  7. 24-bit data pointer (record number in DBF)
  869.  8. 16-bit forward node pointer (for non-leaf nodes, 0 if leaf node)
  870.  9. Repeat 6 to 8 for each key on node. (node size is 512 bytes)
  871. See: Specs_Index_c                                                      -MORE-
  872. ~Specs_Index_c
  873. As in many b-tree implementations, BULLET's index files maintain an average
  874. load percentage of approximately 66%. This means that in any given node, 66% of
  875. the available space is in use. The free space in the node is attributable to
  876. the constant reshaping of the file as keys are inserted or deleted, causing the
  877. nodes to be split and merged. A split will occur when an insert needs to add a
  878. key to an already full node; a merge will occur when a neighboring node is
  879. small enough to be merged into a just split node. This constant prune-and-graft
  880. of the b-tree results in a node load of about 66% (50% in degenerate cases such
  881. as with already sorted data). It's this aspect of the b-tree that makes it a
  882. consistent performer and a widely-used method of managing index files.
  883. The following formula can be used to determine the number of keys that an index
  884. file can hold:
  885.   MaxKeys = MaxNodes * MaxKeysPerNode * LoadFactor
  886.   MaxKeys = 65535 * 509/(keylen+5) * .66
  887. The load factor can be increased to ~95% by using the ReindexXB routine. This
  888. load factor results in superior retrieval speeds since there are more keys on
  889. each node. Insertion speed will be decreased, however, since splitting will
  890. occur more frequently, though perhaps not noticeably.
  891. See: Specs_Memory
  892. ~Specs_Memory
  893. BULLET allocates memory on an as-needed basis. When linked to an executable
  894. program, BULLET makes use of 17.5K of code space and about 1.5K of static
  895. DGROUP data space. To accomodate the wide variety of compilers, BULLET's API
  896. structure will have the linker included all of the library into your final EXE
  897. program.
  898. All runtime memory allocations are obtained from the operating system (the
  899. far heap).
  900. The amount of memory that BULLET requires is based on which routines are used.
  901. See the next screen for a list of the routines that make malloc calls to the
  902. operating system and how much memory they require.
  903. Note that the malloc calls are made with DOS INT21/48 except when using
  904. BULLET_L.LIB, then malloc()/free() is used.
  905. See: Specs_Memory_a  MemoryXB                                           -MORE-
  906. ~Specs_Memory_a
  907. Routines making dynamic memory allocations and amount (within 
  908.  16 bytes):
  909.   Routine           Bytes        Basis
  910. InitXB                  272   permanent, released when program ends (JFTmode=1)
  911. BackupFileXB             32K  temp, released when routine exits
  912. CreateDXB        48+(NF*32)   temp, released when routine exits (NF=NoFields)
  913. CreateKXB               544   temp, released when routine exits
  914. OpenDXB     144+((1+NF)*32)   semi-permanent, released when file closed
  915. OpenKXB                1264   semi-permanent, released when file closed
  916. PackRecordsXB      RL to 64K  temp, released when routine exits (RL=RecLength)
  917. ReindexXB        32K to 128K  temp, released when routine exits
  918. UpdateXB              2K+RL   temp, released when routine exits (RL=RecLength)
  919. For example, when BackupFileXB is called it attempts to allocate 32K from the
  920. OS. If 32K is not available, BackupFileXB returns with an error code of 8 (DOS
  921. error #8, not enough memory). If you won't be using Backup or Reindex, BULLET
  922. can make do with much less memory (use table above).
  923. Needed stack space is 4K (max) for ReindexXB. Other routines can operate with
  924. less than 1K of stack space. In other words, stack use is minimal.
  925. See: Specs_OS_calls
  926. ~Specs_OS_calls
  927. BULLET makes use of the following operating system calls:
  928. INT21/25 DOS_setvector                  INT21/44/0B DOS_setsharingretrycount
  929. INT21/2A DOS_getdate                    INT21/48 DOS_malloc
  930. INT21/30 DOS_version                    INT21/49 DOS_free
  931. INT21/35 DOS_getvector                  INT21/51 DOS_getpsp
  932. INT21/39 DOS_makedir                    INT21/56 DOS_renamefile
  933. INT21/3D DOS_openfile                   INT21/59 DOS_getextendederror
  934. INT21/3E DOS_closefile                  INT21/5A DOS_createtempfile
  935. INT21/3F DOS_readfile                   INT21/5B DOS_createnewfile
  936. INT21/40 DOS_writefile                  INT21/5C DOS_lockunlockfile
  937. INT21/41 DOS_deletefile                 INT21/65/01 DOS_getextendedcountryinfo
  938. INT21/42 DOS_movefileptr                INT21/65/06 DOS_getcollatesequencetable
  939. INT21/44/09 DOS_isdriveremote           INT21/67 DOS_sethandlecount
  940. INT21/44/0A DOS_isfileremote            INT2F/10/00 DOS_isshareinstalled
  941. No other operating system calls are made. No BIOS calls are made.
  942. See: Specs_Languages
  943. ~Specs_Languages
  944. BULLET is compatible with most DOS compilers. The only requirements are that
  945. your compiler allow you to:
  946.  1. Call a library routine via a FAR call using PASCAL calling convention
  947.  2. Pass a far pointer (of the parameter pack) on the stack, by value
  948.  3. Supply far pointers to the various pack parameters
  949.  4. Be able to return an integer value from the FAR call
  950.     (this is optional but recommended for the transaction-based routines)
  951. These requirements can be met with most BASIC, C, and other-language DOS
  952. compilers.
  953. CZ online help is currently available in BASIC and C versions. Others are
  954. pending. You should be able to do well with either of these versions using
  955. other-language compilers since the only difference is the source code examples.
  956. See: Specs_OSes
  957. ~Specs_OSes
  958. BULLET is currently available only for MS-DOS and compatible operating systems.
  959. It requires DOS 3.3 or higher.
  960. To provide efficient memory use, BULLET uses a single-buffer cache per index
  961. file. The single-buffer cache also provides for very quick network access since
  962. a minimum amount of memory needs to be flushed when releasing control of BULLET
  963. files. For maximum speed, however, an external high-performance disk cache can
  964. be used. Hyperdisk is a good choice (shareware, $50+). A properly configured
  965. cache can increase BULLET's performance from 10 to 300%. The most improvement
  966. is with the InsertXB routine. The least is with ReindexXB and PackRecordsXB,
  967. which do most of their work in temporarily allocated memory. Hyperdisk is about
  968. the best designed disk cache available for PCs. SmartDRV 4.x is also good.
  969. If you do not use a disk cache then it's recommended that you set your BUFFERS=
  970. statement in CONFIG.SYS to at least 20 or 30. Even without a disk cache, BULLET
  971. is still very fast. Also, be sure to set your FILES= to the number of files
  972. that you'll be opening at any one time. If you set FILES=20 you can have BULLET
  973. open 14 files (CZ.COM uses 1 and DOS reserves 5 more). You can set FILES=255
  974. allowing BULLET to open up to 249 files at one time.
  975.                  DO NOT set FILES= to a value greater than 255.
  976. See: Specs_Networks
  977. ~Specs_Networks
  978. BULLET currently operates on all DOS-compatible network platforms.
  979. Be sure to install SHARE.EXE (or compatible) on the server and, if you are
  980. mutlitasking, on your local machine. If you'll be opening many files you
  981. should extended the default SHARE file-sharing information space and the number
  982. of locks that can performed at one time. The DOS 5.0 default is /F:2048 and
  983. /L:20. This allocates 2K for file-sharing info space and allows 20 consecutive
  984. locks to be active. If the F: value is too low, error 5 (extended error 32) is
  985. returned on an open attempt. If you extend the JFT in InitXB and plan to use
  986. many files, say more than 50, be sure to extend /F: by 2K for every 50
  987. additional files and set the /L: to the number of files you plan on having
  988. open. If L: is too low, error 1 (ext err 36) is returned on a lock attempt.
  989. As an example, if you'll be using 100 files, set FILES=106 in CONFIG.SYS, set
  990. SHARE /F:4096 /L:106, and IP.JFTmode=1 for InitXB. These values are a minimum.
  991. If you have more than one process active, you need to account for other apps.
  992. Note that Windows always returns a "SHARE is installed" using the DOS detection
  993. routines used by BULLET. To determine if SHARE is actually installed, attempt
  994. to perform a lock using one of the LockXB routines. An error code indicates
  995. that SHARE (or compatible) is not installed.
  996. See: Specs_Performance
  997. ~Specs_Performance
  998.  Test: Reindex 1,000 to 1,000,000 records (BC_LAI10.C)
  999.        DBF: extended DBF using binary sort field
  1000.        key: LONG+SIGNED+UNIQUE                        Machine: 486/33 SHO
  1001.  1Meg
  1002.                                                      *
  1003.      
  1004.      
  1005.                                     *
  1006.      
  1007.                    Records  Time  Reindex Rate
  1008.      
  1009.        *           -------  ----  ------------
  1010.  100k
  1011.   *                   1000   < 1  1000+/sec
  1012.      
  1013.                       5000     2    2500
  1014.      
  1015.  *                   10000     4    2500
  1016.      
  1017. *                    25000     7    3571   3500+ records indexed/second!
  1018.      
  1019.                      50000    14    3571   Times in table are in seconds
  1020.   10k
  1021. *                   100000    28    3571
  1022.      
  1023.                     200000    81    2469
  1024.      
  1025. *                   500000   355    1408
  1026.      
  1027.                    1000000  1124     890
  1028.    1k
  1029.      
  1030.  time (secs)  100       200       300       400       18:00     20:00 (min)
  1031. See: Specs_Overall
  1032. ~InitXB
  1033. Pack: InitPack          Src: InitXBsrc          Func:   0/System
  1034. Before using any routine you must initialize the BULLET file system.
  1035. If you want more than the standard number of file handles, set InitPack.JFTmode
  1036. to 1. This expands the current process's Job File Table to allow 255 open files
  1037. maximum.
  1038. On return the DOS version (INT21/30h) is in InitPack.DOSver. Major version in
  1039. the high byte. Minor in the low. The BULLET version (*100) is returned as is
  1040. the address of the ExitXB routine. You can use this address to register ExitXB
  1041. with your own _atexit function if your runtime library does not provide _atexit
  1042. already.
  1043. Note: _atexit is a routine available in most DOS, OS/2, and ANSI runtime
  1044. library code and is called just prior to the program ending. See AtExitXB for
  1045. information on what to do if your library does not have _atexit.
  1046. See: ExitXB
  1047. ~ExitXB
  1048. Pack: ExitPack          Src: ExitXBsrc          Func:   1/System
  1049. Before ending your program you should call ExitXB to close any open BULLET
  1050. files. This also will release any memory still allocated to those files.
  1051. This restores the default keyboard break handlers if they were changed.
  1052. In normal operation you would see to closing all files yourself. However, if
  1053. your program fails to reach the programmed end, it's very possible that files
  1054. may still be left open. It is essential that you properly close all BULLET
  1055. files before ending. There are two methods to achieve this:
  1056. 1. Direct you startup code so that on fatal errors, your program executes
  1057. ExitXB before returning to DOS.
  1058. 2. Use AtExitXB to automatically register ExitXB to be executed in the normal
  1059. shut-down code of the compiler. This method is preferred.
  1060. See: AtExitXB
  1061. ~AtExitXB
  1062. Pack: ExitPack          Src: AtExitXBsrc        Func:   2/System
  1063. Used to automatically close all BULLET files, release allocated memory, and
  1064. restore the default Break handlers when your program ends. Your compiler
  1065. generates specific code to be executed in the course of ending your program.
  1066. AtExitXB registers the ExitXB routine to be performed in this compiler-
  1067. generated code.
  1068. This routine is standard in most DOS, OS/2, and ANSI runtime libraries. If   
  1069. yours does not have _atexit, then you must link with the supplied            
  1070. NOATEXIT.OBJ file:                                                           
  1071.                                                                              
  1072. C>link YOURPRG + NOATEXIT, ...                                               
  1073. You can tell if your compiler doesn't supply _atexit at link time. LINK reports
  1074. '_atexit' : unresolved external. Add NOATEXIT.OBJ as described above.
  1075. Be sure that your _atexit routine is for the medium, large, or huge memory
  1076. models since BULLET uses multiple code segments and far calls.
  1077. See: MemoryXB  ExitXB  BreakXB
  1078. ~MemoryXB
  1079. Pack: MemoryPack        Src: MemoryXBsrc        Func:   3/System
  1080. This is the only BULLET routine that can be used before InitXB. It reports the
  1081. largest free block of memory available from the OS. This memory does not
  1082. include fragmented memory or UMB memory that BULLET can and will use.
  1083. With DOS able to use UMB memory, memory for BULLET requests may be provided
  1084. from this region. You can use StatPack.HereSeg from StatXB to locate from which
  1085. segment address the allocations are being made. Anything above C800h is UMB.
  1086. See: BreakXB  StatXB  OpenDXB  OpenKXB
  1087. ~BreakXB
  1088. Pack: BreakPack         Src: BreakXBsrc         Func:   4/System
  1089. Disables system response to Control-C and Control-Break keys preventing users
  1090. from inadvertently exiting the program without first doing a BULLET shutdown.
  1091. It's REQUIRED that you reinstate the default break handlers with this routine
  1092. before ending your program. ExitXB automatically reinstates the default break
  1093. handlers.                                                                    
  1094. This routine will not disable Control-Alt-Delete (a warm-boot). If the user is
  1095. at this point, he may prefer to exit via a warm-boot rather than reset the
  1096. machine.
  1097. This routine will not surpress the ^C displayed by DOS. If you don't want the
  1098. ^C to be displayed move the cursor to a location off-screen, say, row 26.
  1099. See: BackupFileXB  ExitXB
  1100. ~BackupFileXB
  1101. Pack: CopyPack          Src: BackupFileXBsrc    Func:   5/System
  1102. Copy an open BULLET key or data file. BULLET repacks and reindexes files in-
  1103. place, requiring less disk space to perform the function. BackupFileXB allows
  1104. you to safely copy a file before doing this.
  1105. This function is recommended prior to packing a data file with PackRecordsXB 
  1106. since the data is very valuable. There is probably little need to do so when 
  1107. reindexing an index file since index files can be constructed very easily    
  1108. from the data file but a CopyKHXB to preserve the key expression is quick    
  1109. and recommended.                                                             
  1110. See: StatHandleXB  PackRecordsXB  ReindexXB
  1111. ~StatHandleXB
  1112. Pack: StatHandlePack    Src: StatHandleXBsrc    Func:   6/System
  1113. Get information on a DOS file handle number to determine if it is a BULLET file
  1114. and if so, if that file is a BULLET key or data file.
  1115. If the returned ID value is 0, the handle is to a BULLET index file. ID=1 then
  1116. the handle is a BULLET .DBF file. ID= -1 then the handle is not a BULLET file.
  1117. See: CreateDXB  StatDXB  StatKXB
  1118. ~GetExtErrorXB
  1119. Pack: XErrorPack        Src: GetExtErrorXBsrc   Func:   7/System
  1120. Get the extended error information for the last operation. This information
  1121. includes the extended error code, the error class, the recommended action, and
  1122. the location of the error. See Errors_DOS for the extended error meaning an
  1123. Errors_DOS_c for the class, action, and locus code meanings.
  1124. Note that on fatal DOS errors, such as an open floppy drive door, the extended
  1125. error code returned is 83 - fail on INT24. This indicates that the INT24
  1126. handler was invoked by DOS and that the INT24 handler told DOS to ignore the
  1127. error. (BULLET invokes its own INT24 handler each time it accesses the DOS file
  1128. system and restores it promptly after the access.) In such cases, this extended
  1129. error code is less informative than the standard return code and, the other
  1130. 'extended' information should be disregarded. (In fatal DOS errors the standard
  1131. return code IS the extended error code.)
  1132. This routine returns the extended error information for the LAST DOS system  
  1133. error. This information remains the same until the next DOS system error.    
  1134. See: CreateDXB  Errors_DOS
  1135. ~DVmonCXB
  1136. Pack: DVmonPack         Src: DVmonCXBsrc        Func:   9/DEBUG
  1137. Control BULLET debug monitor.
  1138. This routine is available only in the debug engine.                          
  1139. The monitor displays in realtime the state of a data file handle, or an index
  1140. and data file handle pair if an index handle is specified. DVmonCXB is best
  1141. used on dual-display systems in which the video output is sent to the secondary
  1142. video monitor. In any case, a 4000-byte screen image is updated in real-time.
  1143. To use the monitor, set mode=1, handle=file to monitor, and VideoSeg=segment
  1144. address of 4000-byte area. The typical VideoSeg would be to video memory. If
  1145. you have a color system as the main monitor and a mono as the secondary, set
  1146. VideoSeg=0xB000. Detail system stats are continually updated to the secondary
  1147. monitor. If you have a single monitor with at least 2 video pages, set VideoSeg
  1148. to your base address plus the page size\16, typically 0xB800+(4096/16). If you
  1149. have only a single-page video system, you can allocate a 4000-byte memory area
  1150. and update the video manually by moving it to your video display (80x25).
  1151. See: CreateDXB  StatDXB  StatKXB
  1152. ~CreateDXB
  1153. Pack: CreateDataPack    Src: CreateDXBsrc       Func:  10/Mid-level
  1154. Create a new BULLET .DBF data file. Before using this routine allocate a field
  1155. description array of TYPE FieldDescType for at least as many fields as are in
  1156. the record.
  1157. Conventional dBASE .DBF files have a FileID=3. Other possible FileIDs that you
  1158. may come across are (in hex):
  1159.  43h \__ are special-use Xbase IV DBF files, BULLET can process these file IDs
  1160.  63h /                                    since they are similar to ID type 3
  1161.  83h --- this DBF file has an Xbase III/III+ memo field/file
  1162.  88h --- this DBF file has an Xbase IV memo field/file
  1163. In creating your .DBF files, specify FileID=3 to ensure compatibility across 
  1164. Xbase versions.                                                              
  1165. BULLET makes no special use of the FileID byte.
  1166. See: OpenDXB  FieldDescType  CreateKXB
  1167. ~OpenDXB
  1168. Pack: OpenPack          Src: OpenDXBsrc         Func:  11/Mid-level
  1169. Open an existing .DBF data file for use. You need to specify two things, the
  1170. filename and the DOS file access mode. If the open succeeds, the DOS file
  1171. handle is returned. Use this handle for all further access to this file.
  1172. Each .DBF data file you open allocates 144+((1 + number of fields) * 32) bytes
  1173. for internal use. This memory is not deallocated until you close the file with
  1174. CloseDXB or execute ExitXB.
  1175. You must open the data file before you can open (or create) any of its index
  1176. files.
  1177. See: CloseDXB  OpenKXB
  1178. ~CloseDXB
  1179. Pack: HandlePack        Src: CloseDXBsrc        Func:  12/Mid-level
  1180. Close an existing .DBF data file for use. Closing the file updates the file
  1181. header and deallocates the memory used by this file.
  1182. You MUST close all BULLET files before ending your program or file corruption
  1183. may occur. To ensure that all files are closed in the event of an unscheduled
  1184. program termination, use AtExitXB.                                           
  1185. See: StatDXB  ExitXB  CloseKXB
  1186. ~StatDXB
  1187. Pack: StatDataPack      Src: StatDXBsrc         Func:  13/Mid-level
  1188. Get basic information on the BULLET .DBF data file handle specified.
  1189. Information returned includes the number of records in the file, the record
  1190. length, number of fields per record, and the date the file was last updated.
  1191. Typically, your program will keep track of whether a particular handle belongs
  1192. to a data file or a key file. In cases where this is not possible, call the
  1193. StatHandleXB routine to determine what file type a handle is.
  1194. Note that a just-created data file will have the LastUpdate date set to 0/0/0.
  1195. See: ReadDHXB  StatKXB  StatHandleXB
  1196. ~ReadDHXB
  1197. Pack: HandlePack        Src: ReadDHXBsrc        Func:  14/Mid-level
  1198. Reload the disk copy of the data header for the opened .DBF data file handle
  1199. to the internal copy.
  1200. In single-user, single-tasking systems this routine is not needed. However, in
  1201. a multi-user or multi-tasking system it's possible, and desirable, for two or
  1202. more programs to use the same data file. Consider this scenario: A data file
  1203. has 100 records. Two programs access this data file, both opening it. Program 1
  1204. locks the file, adds a new record, then flushes and unlocks the file. Program 1
  1205. knows that there are now 101 records in the file. However, Program 2 is not
  1206. aware of the changes that Program 1 made--it thinks that there are still 100
  1207. records in the file. This out-of-sync situation is easily remedied by having
  1208. Program 2 reload the data header from the file on disk.
  1209. How does Program 2 know that it needs to reload the header? It doesn't. Instead
  1210. BULLET uses a simple yet effective approach when dealing with such problems.
  1211. Whenever your program locks a file, BULLET automatically reloads the header.
  1212. Whenever you unlock a file, BULLET automatically flushes the header.
  1213. See: FlushDHXB  ReadKHXB  LockXB
  1214. ~FlushDHXB
  1215. Pack: HandlePack        Src: FlushDHXBsrc       Func:  15/Mid-level
  1216. Write the internal copy of the data header for the opened .DBF data file handle
  1217. to disk. The actual write occurs only if the header has been changed.
  1218. This is to ensure that the data header on disk matches exactly the data header
  1219. that is being maintained by BULLET. Also, this routine updates the operating
  1220. system's directory entry for this file.
  1221. Assume the following: A data file with 100 records. Your program opens the data
  1222. file and adds 1 record. Physically, there are 101 records on disk. However, the
  1223. header image of the data file on disk still reads 100 records. This isn't a
  1224. problem, BULLET uses its internal copy of the data header and the internal copy
  1225. does read 101 records. BUT, if there were a system failure now, the disk image
  1226. would not get updated. After the system restart, BULLET opens the file, reads
  1227. the header and thinks that there are 100 records. You lost a record. Now, if
  1228. after that add above, your program issued a FlushDHXB, the header on disk is
  1229. refreshed with the internal copy, keeping the two in-sync. Also, the routine
  1230. updates the DOS directory entry, keeping things neat there as well. Still, it
  1231. doesn't come without cost: flushing will take additional time, therefore, you
  1232. may elect to flush periodically, or whenever the system is idle.
  1233. See: CopyDHXB  ReadDHXB  FlushKHXB  LockXB
  1234. ~CopyDHXB
  1235. Pack: CopyPack          Src: CopyDHXBsrc        Func:  16/Mid-level
  1236. Copy the .DBF file structure of an open data file to another DOS file.
  1237. This routine makes it easy for you to duplicate the structure of an existing
  1238. .DBF file without having to specify all the information needed by CreateDXB.
  1239. The resultant .DBF will be exactly like the source, including number of fields
  1240. and field descriptions. It will contain 0 records.
  1241.      
  1242. See: ZapDHXB  CopyDHXB
  1243. ~ZapDHXB
  1244. Pack: HandlePack        Src: ZapDHXBsrc         Func:  17/Mid-level
  1245. Delete all records for a .DBF data file.
  1246. This routine is similar to CopyDHXB except for one major difference: ALL DATA
  1247. RECORDS IN THE *SOURCE* FILE ARE PHYSICALLY DELETED, so be *careful*.
  1248. If you have a .DBF file with 100 records and use ZapDHXB on it, all 100 records
  1249. will be physically deleted and the file truncated to 0 records. There is no
  1250. return from this routine. All data is gone.
  1251.                            
  1252.                            
  1253. * C A U T I O N *
  1254.                            
  1255.      
  1256. See: CreateKXB  CopyDHXB  ZapKHXB
  1257. ~CreateKXB
  1258. Pack: CreateKeyPack     Src: CreateKXBsrc       Func:  20/Mid-level
  1259. Create a new BULLET key file. Before you can create a key file, you must first
  1260. have opened (and have created if necessary) the BULLET .DBF data file that it
  1261. is to index. (BULLET couples index and data files tightly.)
  1262. To create the key file, you need to provide the key expression, key flags, .DBF
  1263. file link handle, and optionally, the code page ID, country code, and collate
  1264. table.
  1265.                                 Key Expression
  1266. The key expression is an ASCII character string composed of the elements that
  1267. are to make up this index file's key. The key can be composed of any or all of
  1268. the fields in the .DBF data record or sub-strings within any of those fields.
  1269. Two functions are supported in evaluating a key expression. These are SUBSTR()
  1270. and UPPER(). SUBSTR() extracts part of a string starting at a particular
  1271. position for x number of characters. UPPER() converts all lower-case letters to
  1272. their upper-case equivalent. Since BULLET supports NLS, UPPER() conversion is
  1273. not required for proper sorting of mixed-case text strings.
  1274. See: CreateKXB_a  CreateDXB                                             -MORE-
  1275. ~CreateKXB_a
  1276. All names used in the key expression must be a valid field name in the DBF data
  1277. file. Some sample key expressions given that the .DBF has the following fields:
  1278.  Fields...             Valid key expressions
  1279.      
  1280.  FNAME C 25 0       "LNAME"            (all must be 0-terminated)
  1281.  LNAME C 25 0       "LNAME+FNAME"
  1282.  SSN   C  9 0       "SUBSTR(LNAME,1,4)+SUBSTR(FNAME,1,1)+SUBSTR(SSN,6,4)"
  1283.  DEPT  N  5 0       "UPPER(LNAME+FNAME)"  (for non-NLS index files)
  1284.   :     :           "DEPT+SSN" (N- + C-type is valid for non-binary keys)
  1285.                                     Key Flags
  1286. The key expression is used in conjunction with the key flags to determine the
  1287. type of key generated.
  1288. First, if your index file is to disallow duplicate keys, add 1 to KeyFlag.
  1289. If you have a key composed of a character field(s) or portions thereof, you
  1290. specify a KeyFlag = 2. This instructs BULLET that the sort order is left-to-
  1291. right (proper mixed-case sorting is available, see code page ID).
  1292. See: CreateKXB_b                                                        -MORE-
  1293. ~CreateKXB_b
  1294. If you have a key composed of a numeric field(s) or portions thereof, you can
  1295. also specify a KeyFlag = 2. This instructs BULLET to treat the numeric field
  1296. as a regular character field for sorting. To ensure proper sorting, you must
  1297. decimal-align the +numeric strings in the .DBF data field, i.e., right-justify
  1298. the numeric strings (dBASE .DBF numeric strings are stored as ASCII strings).
  1299. These non-binary numeric fields are just like character fields to BULLET.
  1300. In addition, if you have a key composed of a SINGLE numeric field (fld type N)
  1301. and the field is an integer (NO DECIMAL POINT), you can specify a KeyFlag of 16
  1302. or 32. KeyFlag=16 is for a field known to be in word/integer range; KeyFlag=32
  1303. if the field is known to be in LongInt range. These KeyFlag values instruct
  1304. BULLET to sort the key as a 16/32-bit BINARY value. It also stores the key as a
  1305. 16- or 32-bit value (only 2 or 4 bytes) in the index, eventhough the data field
  1306. is in ASCII (keyflag=16 or 32).
  1307. Although not dBASE compatible, you may use BINARY FIELDS in your data records.
  1308. dBASE always has ASCII data in the data fields, even if the field is numeric.
  1309. For example, an N type field of 8.2 is stored as an ASCII text string in the
  1310. data record, say, a string like " 1100.55". If you want dBASE compatibility
  1311. your field data must also be ASCII. However, if you can forgo this requirement,
  1312. you can use binary values in the fields.
  1313. See: CreateKXB_c                                                        -MORE-
  1314. ~CreateKXB_c
  1315. To do this you must specify a field type of "B" (actually, anything but a "N")
  1316. and, IF IT IS TO BE USED AS A KEY FIELD, also set the 16- or 32-bit KeyFlag.
  1317. Unique and signed may also be flagged. The field length for a "B" field type is
  1318. 2 or 4. Make sure the key flags match (2 if cINTEGER, 4 if cLONG).
  1319. If you specify a binary key flag (for either N or B field types), you must also
  1320. specify whether the field is to be treated as a signed or unsigned value. If
  1321. values less than 0 are possible, add to KeyFlag the hex number 0x8000.
  1322.  KeyFlag = cUNIQUE|cCHAR;          /* unique character key (NLS sort)      */
  1323.  KeyFlag = cINTEGER|cUNIQUE;       /* unique unsigned integer (binary sort)*/
  1324.  KeyFlag = cUNIQUE|cSIGNED|cLONG;  /* unique signed long                   */
  1325.  KeyFlag = cCHAR;                  /* character key with duplicates allowed*/
  1326.  KeyFlag = cCHAR|cINTEGER;         /* THIS IS AN INVALID KEY FLAGS!        */
  1327. The following values are defined in BULLET.H:
  1328.   cUNIQUE=1, cCHAR=2, cINTEGER=0x10, cLONG=0x20, cNLS=0x4000, cSIGNED=0x8000
  1329. The NLS flag is assigned by BULLET. StatKXB is used to query KeyFlags.
  1330. See: CreateKXB_d                                                        -MORE-
  1331. ~CreateKXB_d
  1332. The key expression you specify may be up to 136 characters, and evaluate out to
  1333. 64 bytes (62 bytes if unique key is not specified). I.e, "SUBSTR(..." can
  1334. be up to 136 characters, and that the actual key built from this expression can
  1335. be no longer that 64 bytes, or 62 if you did not specify UNIQUE. In general,
  1336. shorter keys (the key itself, not the expression) offer better performance.
  1337.                          DBF File Link Handle (XBlink)
  1338. Since BULLET evaluates the key expression at CreateKXB, it must have access to
  1339. the DBF file to verify that the key expression is valid. You must therefore
  1340. supply CreateKXB with the OS file handle of the opened DBF data file.
  1341. National Language Support (NLS)
  1342. With DOS 3.3 and later, NLS is available. BULLET uses NLS to build the collate
  1343. sequence table that it uses to ensure proper sorting of mixed-case keys as well
  1344. as the sorting of foreign language alphabets. In order for BULLET to use the
  1345. proper collate table, it must know what code page ID and coutry code to use.
  1346. This table is made part of the index file so that all subsequent access to the
  1347. index file maintains the original sort order, even if the MIS shop is moved to
  1348. another location/computer system using another country code/code page.
  1349. See: CreateKXB_e                                                        -MORE-
  1350. ~CreateKXB_e
  1351.                                 Code Page ID
  1352. To use the default code page ID of the computer in use, specify a code page ID
  1353. of -1. This instructs BULLET to use the collate-sequence table as provided by
  1354. MS-DOS running on the machine. You may also specify the code page ID for BULLET
  1355. to use, but only if support for the code page ID is available on your machine.
  1356. Look in your DOS manual under CUSTOMIZING FOR INTERNATIONAL USE for specific
  1357. code page IDs and country codes. See also the COUNTRY and NLSFUNC commands.
  1358. You may also specify a code page ID = 0 in which case no collate table is used.
  1359.                                 Country Code
  1360. To use the default country code of the computer in use, specify a country code
  1361. of -1. This instructs BULLET to use the collate-sequence table as provided by
  1362. MS-DOS running on the machine. You may also specify the country code for BULLET
  1363. to use, but only if support for the country code is available on your machine.
  1364. Look in your DOS manual under CUSTOMIZING FOR INTERNATIONAL USE for specific
  1365. code page IDs and country codes. See also the COUNTRY and NLSFUNC commands.
  1366. You may also specify a country code = 0 in which case no collate table is used.
  1367. Typically, you set CodePageID = -1, CoutryCode = -1 and CollatePtr = 0.
  1368. See: CreateKXB_f                                                        -MORE-
  1369. ~CreateKXB_f
  1370.                          User-specified Collate Table
  1371. If you are to use a MS-DOS supplied collate table (BOTH codepage ID and country
  1372. codes are non-zero) then you do not need to specify a collate table--DOS will.
  1373. The option to allow a user-specified collate table is to work around some DOS
  1374. versions supplying incorrect collate tables. If you find that the DOS-supplied
  1375. collate table is not valid (it's stored in the second sector of the file) for
  1376. your country, you can supply the table to be used by pointing the CollatePtr
  1377. variables to your in-memory version of a valid collate table. If you want to
  1378. use the DOS-supplied collate table, you MUST set the CollatePtr variables = 0.
  1379. Note: The collate table is a 256-byte table that contains the sort value of
  1380. each character (0-255). For example, the first byte would be 0, second would
  1381. be 1, and so on. Values for characters up to the lower-case letters (ASCII 97)
  1382. are usually as you would expect: "A" has a value of 65. However, the lower-case
  1383. letters have the same value as their upper-case counterparts: "a" also has a
  1384. value of 65. BULLET uses this collate table to ensure proper sorting.
  1385. If you specify EITHER code page ID OR country code = 0 then no collate table
  1386. is used or built. Instead, sorting is done by standard ASCII sort. This is
  1387. somewhat faster but less versatile. Use UPPER() for mixed-case sort if needed.
  1388. See: OpenKXB  CreateKXB
  1389. ~OpenKXB
  1390. Pack: OpenPack          Src: OpenKXBsrc         Func:  21/Mid-level
  1391. Open an existing key file for use.
  1392. Each key file that you open allocates 1264 bytes for internal use. This memory
  1393. is not deallocated until you close the file with CloseKXB or execute ExitXB.
  1394. You must open the data file before you can open its related index file
  1395. because you must supply the handle of the data file that this index files
  1396. indexes.
  1397. See: CloseKXB  OpenDXB
  1398. ~CloseKXB
  1399. Pack: HandlePack        Src: CloseKXBsrc        Func:  22/Mid-level
  1400. Close an open key file. Closing the file updates the file header and
  1401. deallocates the memory used by this file.
  1402. You MUST close all BULLET files before ending your program or file corruption
  1403. may occur. To ensure that all files are closed on the event of an unscheduled
  1404. program termination, use AtExitXB.                                           
  1405. See: StatKXB  ExitXB  CloseDXB
  1406. ~StatKXB
  1407. Pack: StatKeyPack       Src: StatKXBsrc         Func:  23/Mid-level
  1408. Get basic information on a BULLET key file handle specified. Information
  1409. returned includes the number of keys in the file, the key length, the data file
  1410. handle for this key, the last accessed record number of that data file, NLS
  1411. information, and the key flags.
  1412. Typically, your program will keep track of whether a particular handle belongs
  1413. to a key file or a data file. In cases where this is not possible, call the
  1414. StatHandleXB routine to determine what file type a handle is.
  1415. See: ReadKHXB  StatDXB  StatHandleXB
  1416. ~ReadKHXB
  1417. Pack: HandlePack        Src: ReadKHXBsrc        Func:  24/Mid-level
  1418. Reload the disk copy of the key header for the opened key file handle to the
  1419. internal copy.
  1420. In single-user, single-tasking systems this routine is not needed. However, in
  1421. a multi-user or multi-tasking system it's possible, and desirable, for two or
  1422. more programs to use the same data file. Consider this scenario: A key file has
  1423. 100 keys. Two programs access this key file, both opening it. Program 1 locks
  1424. the file, adds a new key, then flushes and unlocks the file. Program 1 knows
  1425. that there are now 101 keys in the file. However, Program 2 is not aware of the
  1426. changes that Program 1 made--it thinks that there are still 100 keys in the
  1427. file. This out-of-sync situation is easily remedied by having Program 2 reload
  1428. the key header from the file on disk.
  1429. How does Program 2 know that it needs to reload the header? It doesn't. Instead
  1430. BULLET uses a simple yet effective approach when dealing with such problems.
  1431. Whenever your program locks a file, BULLET automatically reloads the header.
  1432. Whenever you unlock a file, BULLET automatically flushes the header.
  1433. See: FlushKHXB  ReadDHXB  FlushDHXB  LockXB
  1434. ~FlushKHXB
  1435. Pack: HandlePack        Src: FlushKHXBsrc       Func:  25/Mid-level
  1436. Write the internal copy of the key header for the opened key file handle to
  1437. disk. The actual write occurs only if the header has been changed.
  1438. This is to ensure that the key header on disk matches exactly the key header
  1439. that is being maintained by BULLET. Also, this routine updates the operating
  1440. system's directory entry for this file.
  1441.      
  1442. Assume the following: A data file with 100 keys. Your program opens the key
  1443. file and adds 1 key. Physically, there are 101 keys on disk. However, the
  1444. header image of the data file on disk still reads 100 keys. This isn't a
  1445. problem, BULLET uses its internal copy of the key header and the internal copy
  1446. does read 101 keys. BUT, if there were a system failure now, the disk image
  1447. would not get updated. After the system restart, BULLET opens the file, reads
  1448. the header and thinks that there are 100 keys. You lost a key. Now, if after
  1449. that add above, your program issued a FlushKHXB, the header on disk is
  1450. refreshed with the internal copy, keeping the two in-sync. Also, the routine
  1451. updates the DOS directory entry, keeping things neat there as well. Still, it
  1452. doesn't come without cost: flushing will take additional time, therefore, you
  1453. may elect to flush periodically, or whenever the system is idle.
  1454. See: CopyKHXB  ReadKHXB  FlushKHXB  LockXB
  1455. ~CopyKHXB
  1456. Pack: CopyPack          Src: CopyKHXBsrc        Func:  26/Mid-level
  1457. Copy the key file structure of an open key file to another DOS file.
  1458. This routine makes it easy for you to duplicate the structure of an existing
  1459. key file without having to specify all the information needed by CreateKXB.
  1460. The resultant key file will be exactly like the source, including key flags and
  1461. key expression. It will contain 0 keys.
  1462.      
  1463. See: ZapKHXB  CopyKHXB
  1464. ~ZapKHXB
  1465. Pack: HandlePack        Src: ZapKHXBsrc         Func:  27/Mid-level
  1466. Delete all keys for a key file.
  1467. This routine is similar to CopyKHXB except for one major difference: ALL KEYS
  1468. IN THE *SOURCE* FILE ARE PHYSICALLY DELETED, so be *careful*.
  1469. If you have a key file with 100 keys and use ZapKHXB on it, all 100 keys will
  1470. be physically deleted and the file truncated to 0 keys. There is no return from
  1471. this routine. All data is gone.
  1472.                            
  1473.                            
  1474. * C A U T I O N *
  1475.                            
  1476.      
  1477. See: GetDescriptorXB  CopyKHXB  ZapDHXB
  1478. ~GetDescriptorXB
  1479. Pack: DescriptorPack    Src: GetDescriptorXBsrc Func:  30/Mid-level
  1480. Get the field descriptor information for a field.
  1481. You can specifiy either the fieldname or the field number (position of the
  1482. field within the record where the first field is #1) to get info on.
  1483. The field descriptor contains the following information:
  1484.   FIELDNAME  10 upper-case characters, A-Z and _ allowed, unused space is
  1485.              0-filled and is 0-terminated (11 bytes, ASCII, byte 11 always=0)
  1486.   FIELDTYPE  single ASCII character where C=character, N=numeric, D=date,
  1487.              L=logical, and M=memo field (1 byte, ASCII)
  1488.   FIELDLEN   length of field: C=1-254, N=1-19, D=8 (yyyymmdd), L=1 (T/F/space),
  1489.              M=10, this is total field length (1 byte, binary)
  1490.   FIELDDC    places right of decimal point if N field type, minimum if not 0 is
  1491.              2, can be up to 6 or 8, non-N fields always 0 (1 byte, binary)
  1492. See: GetRecordXB
  1493. ~GetRecordXB
  1494. Pack: AccessPack        Src: GetRecordXBsrc     Func:  31/Mid-level
  1495. Get the physical record from the data file into a data buffer by record number.
  1496. The data buffer is typically a struct variable defined as the DBF record itself
  1497. is defined. For example, if the DBF record has 2 fields, LNAME and FNAME, then
  1498. variable would be struct'ed as:
  1499. struct rectype {
  1500.         char  tag;           /* The Xbase DBF delete flag (must be included) */
  1501.         char  lastname[25];  /* same field length as the .DBF LNAME field    */
  1502.         char  firstname[25]; /* same field length as the .DBF FNAME field    */
  1503. }; /* 51 */
  1504. struct rectype recbuff;
  1505. This method of accessing the data file does not use any indexing. Therefore, it
  1506. typically is not used except for special purposes. The preferred method to
  1507. access the data is by one of the keyed Get() routines.
  1508. See: AddRecordXB  GetEqualXB
  1509. ~AddRecordXB
  1510. Pack: AccessPack        Src: AddRecordXBsrc     Func:  32/Mid-level
  1511. Append the record in the data buffer to the end of the DBF file.
  1512. This method of adding a record does not involve any indexing. It is typically
  1513. used to build a data file en masse and do the indexing after the entire .DBF 
  1514. file(s) has been built.                                                      
  1515. If you have several thousand data records to be added at once, this method of
  1516. building the DBF first and then using the ReindexXB routine is often faster
  1517. than using the InsertXB routine for each record to add.
  1518. The AddRecordXB is very fast. 400 recs/sec on an AT machine is typical. Over
  1519. 2000 recs/sec can be added on a fast 486 machine--that's 120,000 records added
  1520. per minute.
  1521. The record number used is determined by BULLET and it is returned in AP.RecNo.
  1522. See: UpdateRecordXB  InsertXB  ReindexXB
  1523. ~UpdateRecordXB
  1524. Pack: AccessPack        Src: UpdateRecordXBsrc  Func:  33/Mid-level
  1525. Write the updated data record to the the physical record number.
  1526. This method of writing the updated record must not be used if any field(s) in
  1527. the record is used as a key field(s) and has been changed.                   
  1528. This method of updating a record is very fast if you know that that update is
  1529. not going to alter any field used as a key in any index file that uses it. You
  1530. must, of course, first get the data record into the record buffer. Then you can
  1531. change it and write the update out to disk with this routine.
  1532. If you need to change a field(s) that is used as a key field or part of one,
  1533. use the UpdateXB routine. UpdateXB not only dynamically updates all related
  1534. index files if you change a key field, it also will undo any and all changes if
  1535. an error occurs in the transaction.
  1536. See: DeleteRecordXB  GetRecordXB  UpdateXB
  1537. ~DeleteRecordXB
  1538. Pack: AccessPack        Src: DeleteRecordXBsrc  Func:  34/Mid-level
  1539. Tag the record at the physical record number as being deleted.
  1540. This does not tag any in-memory copies of the record so be sure to mark any
  1541. such copies as being deleted yourself.                                     
  1542. The first byte of every .DBF record is reserved for the delete tag. This tag
  1543. is a space (ASCII 32) if the record is normal, or a * (ASCII 42) if it's marked
  1544. as being deleted. This delete tag is a reserved field in the DBF record and as
  1545. such is not defined as a formal field with a descriptor, etc. Make sure that
  1546. you define your in-memory buffers to reserve the first byte for the delete tag.
  1547. The Xbase DBF standard doesn't physically remove records marked as deleted from
  1548. the data file. It doesn't mark them as available/reusable either. To physically
  1549. remove records marked as deleted use PackRecordsXB.
  1550. Records can be temporarily marked as deleted then recalled to normal status.
  1551. The Key/Get routines (GetFirstXB, etc.) return the record number needed for
  1552. this routine after each access in AP.RecNo.
  1553. See: UndeleteRecordXB  PackRecordsXB
  1554. ~UndeleteRecordXB
  1555. Pack: AccessPack        Src: UndeleteRecordsrc  Func:  35/Mid-level
  1556. Tag the record at the physical record number as being normal (not deleted).
  1557. This does not tag any in-memory copies of the record so be sure to mark any
  1558. such copies as being normal yourself.                                      
  1559. The first byte of every .DBF record is reserved for the delete tag. This tag
  1560. is a space (ASCII 32) if the record is normal, or a * (ASCII 42) if it's marked
  1561. as being deleted. This delete tag is a reserved field in the DBF record and as
  1562. such is not defined as a formal field with a descriptor, etc. Make sure that
  1563. you define your in-memory buffers to reserve the first byte for the delete tag.
  1564. The Xbase DBF standard does not physically remove records marked as deleted
  1565. from the data file so you can "recall" then back to normal status as easily as
  1566. you marked them deleted.
  1567. See: PackRecordsXB  DeleteRecordXB
  1568. ~PackRecordsXB
  1569. Pack: AccessPack        Src: PackRecordsXBsrc   Func:  36/Mid-level
  1570. Rebuild the open DBF file by physically removing all records marked as deleted.
  1571. Packing occurs in place using the existing file. It's recommended that you   
  1572. use BackupFileXB to copy the current DBF file before using this routine in   
  1573. case of a failure during the pack process.                                   
  1574. The newly packed file is truncated to reflect the current, actual size.
  1575. If there are index files for this .DBF file, they MUST all be reindexed after
  1576. the pack process by using ReindexXB.
  1577. This routine dynamically allocates at least as many bytes as the length of   
  1578. the record. More if available.                                               
  1579. See: FirstKeyXB  DeleteRecordXB  BackupFileXB  ReindexXB
  1580. ~FirstKeyXB
  1581. Pack: AccessPack        Src: FirstKeyXBsrc      Func:  40/Mid-level
  1582. Retrieve the first key in index order from the index file.
  1583. This routine does not access the .DBF file and so does not retrieve the data 
  1584. record. What it does do is locate the first key of the index, returning it,  
  1585. and also returning the record number within the .DBF that the key indexes.   
  1586. To retrieve the data record you can use the GetRecordXB routine. The preferred
  1587. method, however, is to use the GetFirstXB.
  1588. The key returned includes an enumerator if a non-unique index file is involved.
  1589. The enumerator is a little-endian 16-bit value that serves to differentiate  
  1590. up to 65535 "identical", non-unique keys. It is attached to all keys of non- 
  1591. unique index files and occupies the last two bytes of the key.               
  1592. This routine is typically used to position the index file to the first key so
  1593. as to allow forward in-order access to the keys by using NextKeyXB.
  1594. See: EqualKeyXB  GetFirstXB  GetRecordXB
  1595. ~EqualKeyXB
  1596. Pack: AccessPack        Src: EqualKeyXBsrc      Func:  41/Mid-level
  1597. Search for the exact key in the index file.
  1598. This routine does not access the .DBF file and so does not retrieve the data 
  1599. record. What it does do is search for the key in the index, and if found,    
  1600. returns the record number within the .DBF that the key indexes. The key must 
  1601. be an exact match, including enumerator word if a non-unqiue index file.     
  1602. To retrieve the data record you can use the GetRecordXB routine. The preferred
  1603. method, however, is to use the GetEqualXB.
  1604. This routine will only find EXACT matches to the specified key (including the
  1605. enumerator if applicable). However, even if the exact key is not found in the
  1606. index file, the index file is positioned so that the next NextKeyXB retrieves
  1607. the key that would have followed the unmatched specified key. For example,
  1608. if the key to match was "KINGS" (a partial key in this case), EqualKeyXB would
  1609. return a key not found error. If you were to now do a NextKeyXB, the next key
  1610. would be returned, let's say it is "KINGSTON".  If index file is not unique,
  1611. you must append the enumerator bytes (\0\0 for the first, \0\1 next, ...).
  1612. See: NextKeyXB  GetEqualXB  GetRecordXB
  1613. ~NextKeyXB
  1614. Pack: AccessPack        Src: NextKeyXBsrc       Func:  42/Mid-level
  1615. Retrieve the next key in index order from the index file.
  1616. This routine does not access the .DBF file and so does not retrieve the data 
  1617. record. What it does do is retreive the next key of the index, returning it, 
  1618. and also returning the record number within the .DBF that the key indexes.   
  1619. To retrieve the data record you can use the GetRecordXB routine. The preferred
  1620. method, however, is to use the GetNextXB.
  1621. The key returned includes an enumerator if a non-unique index file is involved.
  1622. This routine is typically called after the index file has first been positioned
  1623. to a known key using either FirstKeyXB or EqualKeyXB, or after a previous
  1624. NextKeyXB or even PrevKeyXB. What it basically does is get the key following
  1625. the current key, and then make that key the new current key.
  1626. See: PrevKeyXB  GetNextXB  GetRecordXB
  1627. ~PrevKeyXB
  1628. Pack: AccessPack        Src: PrevKeyXBsrc       Func:  43/Mid-level
  1629. Retrieve the previous key in index order from the index file.
  1630. This routine does not access the .DBF file and so does not retrieve the data 
  1631. record. What it does do is retreive the previous key of the index, returning 
  1632. it and also returning the record number within the .DBF that the key indexes.
  1633. To retrieve the data record you can use the GetRecordXB routine. The preferred
  1634. method, however, is to use the GetPrevXB.
  1635. The key returned includes an enumerator if a non-unique index file is involved.
  1636. This routine is typically called after the index file has first been positioned
  1637. to a known key using either LastKeyXB or EqualKeyXB, or after a previous
  1638. PrevKeyXB or even NextKeyXB. What it basically does is to get the key previous
  1639. the current key, and then make that key the new current key.
  1640. See: LastKeyXB  GetPrevXB  GetRecordXB
  1641. ~LastKeyXB
  1642. Pack: AccessPack        Src: LastKeyXBsrc       Func:  44/Mid-level
  1643. Retrieve the last key in index order from the index file.
  1644. This routine does not access the .DBF file and so does not retrieve the data 
  1645. record. What it does do is locate the last key of the index, returning it,   
  1646. and also returning the record number within the .DBF that the key indexes.   
  1647. To retrieve the data record you can use the GetRecordXB routine. The preferred
  1648. method, however, is to use the GetLastXB.
  1649. This routine is typically used to position the index file to the last key so as
  1650. to allow reverse in-order access to the keys by using PrevKeyXB.
  1651. See: StoreKeyXB  GetLastXB  GetRecordXB
  1652. ~StoreKeyXB
  1653. Pack: AccessPack        Src: StoreKeyXBsrc      Func:  45/Mid-level
  1654. Insert the key into the index file in proper key order.
  1655. This routine does not add the data record to the .DBF file. It only inserts  
  1656. the key and record number into the index file. Use InsertXB, instead.        
  1657. To do a complete data record and key insert, you could use AddRecordXB to add
  1658. the data record to the .DBF, BuildKeyXB to construct the key, then StoreKeyXB
  1659. to insert the key and record number information into the index file. If that
  1660. key already exists and the file allows duplicate keys, you need to attach the
  1661. proper enumerator word and retry StoreKeyXB.
  1662. This is much too much to do. Instead, just use InsertXB. All these details
  1663. including adding the data record and multi-key inserts are performed
  1664. automatically with just the single call.
  1665. See: DeleteKeyXB  InsertXB
  1666. ~DeleteKeyXB
  1667. Pack: AccessPack        Src: DeleteKeyXBsrc     Func:  46/Mid-level
  1668. Physically remove the specified key from the index file.
  1669. This routine requires an EXACT key match for all bytes of the key, including 
  1670. the enumerator word if a non-unique index file is involved.                  
  1671. This routine would seldom be used, typically, since deleted dBASE data records
  1672. are only physically deleted during a PackRecordsXB and the index file is
  1673. rebuilt afterward using ReindexXB.
  1674. See: BuildKeyXB  CurrentKeyXB
  1675. ~BuildKeyXB
  1676. Pack: AccessPack        Src: BuildKeyXBsrc      Func:  47/Mid-level
  1677. Build the key for the specifed data record based on the key expression for the
  1678. index file. If the index file is non-unique, a 0-value enumerator is attached.
  1679. The enumerator is a little-endian 16-bit value that serves to differentiate  
  1680. up to 65535 "identical", non-unique keys. It is attached to all keys of non- 
  1681. unique index files and occupies the last two bytes of the key.               
  1682. This routine, like most of the mid-level routines, typically would not be used
  1683. since the high-level access routines take care of this detail automatically.
  1684. Note: Little-endian in Bullet means that bit-order is from high to low.
  1685. Sometimes called Motorola format.  The first byte is of higher order than
  1686. the second, so \0\0 precedes \0\1 (then \0\2... \1\0, \1\1, \1\2, (so on)).
  1687. See: CurrentKeyXB  StoreKeyXB
  1688. ~CurrentKeyXB
  1689. Pack: AccessPack        Src: CurrentKeyXBsrc    Func:  48/Mid-level
  1690. Retrieve the current key value for the specified key file handle and also the
  1691. data record number that it indexes.
  1692. This routine is useful in that it retrieves on demand the actual key value of
  1693. the last accessed key in the index file (and the data record number). Most
  1694. often you don't need this information so it would be a waste of time and space
  1695. for your program to explicitly track each current key for each index file that
  1696. you have open.
  1697. See: GetFirstXB  ReindexXB  DeleteKeyXB
  1698. ~GetFirstXB
  1699. Pack: AccessPack        Src: GetFirstXBsrc      Func:  60/High-level
  1700. Retrieve the first indexed key and data record.
  1701. The key returned includes an enumerator if a non-unique index file is involved.
  1702. This routine is typically used to process a database in index order starting at
  1703. the first ordered key (and its data record). After processing this first entry,
  1704. subsequent in-order access of the database is achieved by using GetNextXB until
  1705. the end of the database is reached.
  1706. This routine, like all the high-level Get routines, fills in the AP.RecNo of
  1707. the record accessed. In GetFirstXB's case, it fills AP.RecNo with the record
  1708. number pointed to by the first key. Since this is so, the AP pack is primed for
  1709. an UpdateXB after each high-level Get. Other methods to get the record number
  1710. are to use CurrKeyXB or any of the Key routines (KeyFirstXB, etc.).
  1711. See: GetEqualXB  FirstKeyXB  UpdateXB
  1712. ~GetEqualXB
  1713. Pack: AccessPack        Src: GetEqualXBsrc      Func:  61/High-level
  1714. Search for the exact key in the index file and return its data record.
  1715. This routine will only find EXACT matches to the specified key (including the
  1716. enumerator if applicable). However, even if the exact key is not found in the
  1717. index file, the index file is positioned so that the next GetNextXB retrieves
  1718. the key that would have followed the unmatched specified key. For example,
  1719. if the key to match was "KINGS" (a partial key in this case), GetEqualXB would
  1720. return a key not found error. If you were to now do a GetNextXB, the next key
  1721. and data record would be returned, let's say the key is "KINGSTON" and its data
  1722. record is the data record for that key. Another GetNextXB would retrieve the
  1723. key and record after that. (GetPrevXB can be used in this fashion too.)
  1724. This routine, like all the high-level Get routines, fills in the AP.RecNo of
  1725. the record accessed. In GetEqualXB's case, it fills AP.RecNo with the record
  1726. number pointed to by the matched key. Since this is so, the AP pack is primed
  1727. for an UpdateXB after each high-level Get. Other methods to get the record
  1728. number are to use CurrKeyXB or any of the Key routines (KeyEqualXB, etc.).
  1729. See: GetNextXB  EqualKeyXB
  1730. ~GetNextXB
  1731. Pack: AccessPack        Src: GetNextXBsrc       Func:  62/High-level
  1732. Retrieve the next indexed key and its data record.
  1733. The key returned includes an enumerator if a non-unique index file is involved.
  1734. This routine is typically calld after the index file has first been positioned
  1735. to a known key using either GetFirstXB or GetEqualXB, or after a previous
  1736. GetNextXB or even GetPrevXB. What it basically does is get the key and data
  1737. record following the current key, and then make that key the new current key.
  1738. This routine, like all the high-level Get routines, fills in the AP.RecNo of
  1739. the record accessed. In GetNextXB's case, it fills AP.RecNo with the record
  1740. number pointed to by the next key. Since this is so, the AP pack is primed for
  1741. an UpdateXB after each high-level Get. Other methods to get the record number
  1742. are to use CurrKeyXB or any of the Key routines (KeyNextXB, etc.).
  1743. See: GetPrevXB  NextKeyXB
  1744. ~GetPrevXB
  1745. Pack: AccessPack        Src: GetPrevXBsrc       Func:  63/High-level
  1746. Retrieve the previous indexed key and record.
  1747. The key returned includes an enumerator if a non-unique index file is involved.
  1748. This routine is typically called after the index file has first been positioned
  1749. to a known key using either GetLastXB or GetEqualXB, or after a previous
  1750. GetPrevXB or even GetNextXB. What it basically does is to get the key and data
  1751. record previous the current key, and then make that key the new current key.
  1752. This routine, like all the high-level Get routines, fills in the AP.RecNo of
  1753. the record accessed. In GetPrevXB's case, it fills AP.RecNo with the record
  1754. number pointed to by the previous key. Since this is so, the AP pack is primed
  1755. for an UpdateXB after each high-level Get. Other methods to get the record
  1756. number are to use CurrKeyXB or any of the Key routines (KeyPrevXB, etc.).
  1757. See: GetLastXB  PrevKeyXB
  1758. ~GetLastXB
  1759. Pack: AccessPack        Src: GetLastXBsrc       Func:  64/High-level
  1760. Retrieve the last indexed key and record.
  1761. This routine is typically used to process a database in reverse index order
  1762. starting at the last ordered key (and its data record). After processing this
  1763. last entry, subsequent reverse-order access of the database is achieved by
  1764. using GetPrevXB until the top of the database is reached.
  1765. This routine, like all the high-level Get routines, fills in the AP.RecNo of
  1766. the record accessed. In GetLastXB's case, it fills AP.RecNo with the record
  1767. number pointed to by the last key. Since this is so, the AP pack is primed for
  1768. an UpdateXB after each high-level Get. Other methods to get the record number
  1769. are to use CurrKeyXB or any of the Key routines (KeyLastXB, etc.).
  1770. See: InsertXB  LastKeyXB
  1771. ~InsertXB
  1772. Pack: AccessPack        Src: InsertXBsrc        Func:  65/High-level
  1773. Add the data record to data file and insert the related key(s) into the linked
  1774. index file(s).
  1775. This routine is used to add new entries into a database, one at a time. The
  1776. data record is first added to the data file, then for each related index file,
  1777. a key is inserted into the appropriate index file. Up to 32 index files can be
  1778. automatically maintained for each data file.
  1779. This and several other routines are transaction-based. If a failure occurs
  1780. prior to the routine's completion, all changes made to the database by the
  1781. routine will be backed-out and the database (data and related index file(s))
  1782. effectively restored to its original state.
  1783.                                   
  1784. If the routine failed to complete, the function return value is the number of
  1785. the pack that caused the failure. The pack's Stat is checked to determine the
  1786. error code. If the function return value is 0, YOU MUST STILL check the first
  1787. pack's Stat. If it's non-zero, then the failure occured with the data record.
  1788. See: UpdateXB  StoreKeyXB
  1789. ~UpdateXB
  1790. Pack: AccessPack        Src: UpdateXBsrc        Func:  66/High-level
  1791. Modify an existing data record (identified by record number) and automatically
  1792. perform any index file updates needed to keep the index file(s) in sync.
  1793. If any key fields changed between the original record and the new one, this
  1794. routine updates the appropriate index file(s) by replacing the original key(s)
  1795. with new the key(s) based on the updated data record. Up to 32 index files can
  1796. be automatically maintained for each data file. Get routines (GetFirstXB, etc.)
  1797. set the AP.RecNo of the record that UpdateXB uses.
  1798. This and several other routines are transaction-based. If a failure occurs
  1799. prior to the routine's completion, all changes made to the database by the
  1800. routine will be backed-out and the database (data and related index file(s))
  1801. effectively restored to its original state.
  1802. If the routine failed to complete, the function return value is the number of
  1803. the pack that caused the failure. The pack's Stat is checked to determine the
  1804. error code. If the function return value is 0, YOU MUST STILL check the first
  1805. pack's Stat. If it's non-zero, then the failure occured with the data record.
  1806. See: ReindexXB  UpdateRecordXB
  1807. ~ReindexXB
  1808. Pack: AccessPack        Src: ReindexXBsrc       Func:  67/High-level
  1809. Reindex all related index files for a data file.
  1810. The index file(s) must already exist and be open. Any existing key data is
  1811. overwritten by the new key data. In other words, if you have a 10MByte index
  1812. file, ReindexXB uses the same file space building the news keys over the old.
  1813. This results in a less fragmented disk and also minimizes disk space needed.
  1814. You can also create a new, empty index file and reindex to that. This would be
  1815. useful, for instance, if you needed to create a temporary index file--something
  1816. that you'd use for a report, say, then delete after the report.
  1817. This routine creates a TEMPORARY work file in either the current directory or,
  1818. if the DOS environment variable TMP is defined, in the TMP= directory. The size
  1819. of this file is approx. bytes = (RECORDS * (KEYLEN+6)). ReindexXB can operate
  1820. in as little as 32K of available memory and can use up to 128K. The resultant
  1821. index file(s) are optimized for minimum size AND maximum retrieval speed.
  1822. If the routine failed to complete, the function return value is the number of
  1823. the pack that caused the failure. The pack's Stat is checked to determine the
  1824. error code. A return value of zero indicates no error occured.               
  1825. See: LockXB  PackRecordsXB
  1826. ~LockXB
  1827. Pack: AccessPack        Src: LockXBsrc          Func:  80/Network
  1828. Lock all bytes in the index file handle(s) for exclusive use by the current
  1829. process and reload the index file header(s) from disk. Also lock all bytes in
  1830. the related data file and reload the data file header from disk.
  1831. The files must have been opened with the appropriate share attribute and not 
  1832. in compatibility mode. SHARE.EXE MUST be installed or DOS error 1 is issued. 
  1833. This routine is transaction-based and will lock all index files specified in 
  1834. AccessPack and the data file. If any lock fails, all previous locks by this  
  1835. routine are released. The return value indicates which access pack failed, if
  1836. any. This value is used as the index into the AccessPack group for you to    
  1837. identify the error code. See LockXBsrc for determining this exactly.         
  1838. Use the DriveRemoteXB and/or FileRemoteXB to determine if locking is necessary.
  1839. If the files are on a remote drive then it is best to use locking. Locking may
  1840. also be necessary on multitasking local machines accessing shared files.
  1841. This routine is a combination of LockKeyXB and LockDataXB.
  1842. See: UnlockXB  LockKeyXB  LockDataXB  DriveRemoteXB  FileRemoteXB
  1843. ~UnlockXB
  1844. Pack: AccessPack        Src: UnlockXBsrc        Func:  81/Network
  1845. Unlock all bytes in the specified file handle(s) (previously locked) and flush
  1846. the file header(s) to disk (flush done before lock(s) released). Also unlock
  1847. all bytes in the related data file and flush the data file header to disk.
  1848. The files must have been opened with the appropriate share attribute and not 
  1849. in compatibility mode. SHARE.EXE MUST be installed or DOS error 1 is issued. 
  1850. This routine is transaction-based and will unlock all index files specified in
  1851. AccessPack and the data file. If an unlock fails the routine exits with a
  1852. return value indicating which access pack failed. This value is used as the
  1853. index into the AccessPack group for you to identify the error code. Note that
  1854. this routine does not attempt to re-lock those files unlocked successfully if
  1855. an error occurs in the transaction. If an error does occur (unlikely) you will
  1856. need to provide for unlocking the remaining files manually with the UnlockKeyXB
  1857. and UnlockDataXB routines. You should not rely on the operating system to
  1858. automatically unlock files when they're closed.
  1859. This routine is a combination of UnlockKeyXB and UnlockDataXB.
  1860. See: LockKeyXB  UnlockKeyXB  UnlockDataXB
  1861. ~LockKeyXB
  1862. Pack: AccessPack        Src: LockKeyXBsrc       Func:  82/Network
  1863. Lock all bytes in the index file handle(s) for exclusive use by the current
  1864. process and reload the index file header(s) from disk.
  1865. The files must have been opened with the appropriate share attribute and not 
  1866. in compatibility mode. SHARE.EXE MUST be installed or DOS error 1 is issued. 
  1867. This routine is transaction-based and will lock all index files specified in
  1868. AccessPack. If any lock fails, all previous locks by this routine are released.
  1869. The return value indicates which access pack failed, if any. This value is used
  1870. as the index into the AccessPack group for you to identify the error code.
  1871. The advantage of using region locks (LockKeyXB locks the entire file region) to
  1872. control file access is that the file does not need to be opened/closed using
  1873. the Deny Read/Write sharing attribute. Opening the file for Deny None, and
  1874. controlling subsequent access with region locks, allows for faster processing
  1875. since files do not need to be constantly opened and closed, as they would if
  1876. access were controlled by opening with Deny Read/Write.
  1877. See: UnlockKeyXB  LockXB
  1878. ~UnlockKeyXB
  1879. Pack: AccessPack        Src: UnlockKeyXBsrc     Func:  83/Network
  1880. Unlock all bytes in the specified file handle(s) (previously locked) and flush
  1881. the file header(s) to disk (flush done before lock(s) released).
  1882. The files must have been opened with the appropriate share attribute and not 
  1883. in compatibility mode. SHARE.EXE MUST be installed or DOS error 1 is issued. 
  1884. This routine is transaction-based and will unlock all index files specified in
  1885. AccessPack. If an unlock fails the routine exits with a return value indicating
  1886. which access pack failed. This value is used as the index into the AccessPack
  1887. group for you to identify the error code.
  1888. All file locks should be released when exclusive access in no longer needed. 
  1889. It is not recommended that you end your program without having released active
  1890. file locks. This is especially a valid concern for DOS versions prior to 5.0.
  1891. DOS 5 releases locks on files that are closed.
  1892. See: LockDataXB  UnlockXB
  1893. ~LockDataXB
  1894. Pack: AccessPack        Src: LockDataXBsrc      Func:  84/Network
  1895. Lock all bytes in the file handle's data file for exclusive use by the current
  1896. process and reload the data file header from disk. You must set AP.RecNo=0 to
  1897. do this. To lock a single record, set AP.RecNo=record# to lock.
  1898. The files must have been opened with the appropriate share attribute and not 
  1899. in compatibility mode. SHARE.EXE MUST be installed or DOS error 1 is issued. 
  1900. This routine locks the specified data file. If the handle specified is that of
  1901. an index file, that index file's related data file handle is used. For single-
  1902. record locks, AP.Handle must have a data file handle specified. Header loading
  1903. is not performed if locking a single record.
  1904. The advantage of using region locks (LockDataXB locks the entire file region)
  1905. to control file access is that the file does not need to be opened/closed using
  1906. the Deny Read/Write sharing attribute. Opening the file for Deny None, and
  1907. controlling subsequent access with region locks, allows for faster processing
  1908. since files do not need to be constantly opened and closed, as they would if
  1909. access were controlled by opening with Deny Read/Write.
  1910. See: UnlockDataXB
  1911. ~UnlockDataXB
  1912. Pack: AccessPack        Src: UnlockDataXBsrc    Func:  85/Network
  1913. Unlock all bytes in the specified file handle (previously locked) and flush the
  1914. data file header to disk (flush done before lock released). To do this you must
  1915. set AP.RecNo=0. To unlock a single record, set AP.RecNo=record# to unlock.
  1916. The files must have been opened with the appropriate share attribute and not 
  1917. in compatibility mode. SHARE.EXE MUST be installed or DOS error 1 is issued. 
  1918. This routine unlocks the specified data file. If the handle specified is that
  1919. of an index file that index file's related datafile handle is used. For single-
  1920. record unlocks, AP.Handle must have a data file handle specified. Flushing is
  1921. not performed if unlocking a single record.
  1922. All file locks should be released when exclusive access in no longer needed. 
  1923. It is not recommended that you end your program without having released active
  1924. file locks. This is especially a valid concern for DOS versions prior to 5.0.
  1925. DOS 5 releases locks on files that are closed.
  1926. See: DriveRemoteXB
  1927. ~DriveRemoteXB
  1928. Pack: RemotePack        Src: DriveRemoteXBsrc   Func:  86/Network
  1929. Determine if specified drive is remote (default drive=0, A:=1, B=2, C=3...).
  1930. This routine uses INT21/44/sub function 09.
  1931. In addition to returning the IsRemote state, this routine sends back the result
  1932. of the DX register and also the install state of SHARE.EXE.
  1933. The meaning of the bitflags in Flags are (where IsRemote=0):
  1934. Bit   Meaning drive...
  1935.  1   1=uses 32-bit sectoring
  1936.  6   1=accepts Generic IOCTL (for INT21/44/0D,0E,0Fh)
  1937.  7   1=accepts Query IOCTL Device (INT21/44/11h)
  1938.  9   1=is local but shared by other computers in the network
  1939. 11   1=accepts Does-Device-Use-Removable-Media (INT21/44/08)
  1940. 13   1=requires media descriptor in FAT
  1941. 14   1=accepts Receive/Send Control Data from Block Device (INT21/44/04,05)
  1942. 15   1=is Substitution drive (set by the DOS SUBST command)
  1943.      (all other bits=0)
  1944. See: FileRemoteXB  LockXB
  1945. ~FileRemoteXB
  1946. Pack: RemotePack        Src: FileRemoteXBsrc    Func:  87/Network
  1947. Determine if specified handle of file or device is remote.
  1948. This routine uses INT21/44/sub function 0Ah.
  1949. In addition to returning the IsRemote state, this routine sends back the result
  1950. of the DX register and also the install state of SHARE.EXE.
  1951. Flags bit 7=1 then handle is device, =0 then handle is file.
  1952. Bit   Meaning DEVICE...                 Bit   Meaning DEVICE...(cont)
  1953.  0   1=is console input device          13   1=is named pipe
  1954.  1   1=is console output device         15   1=is remote, 0=is local
  1955.  2   1=is null device                        (all other bits=0)
  1956.  3   1=is clock device                  Bit   Meaning FILE...
  1957.  4   1=is special device               0-5   xxxxxx=drive number (0=A...)
  1958.  5   1=is in binary mode, 0=in ASCII     6   1=has not been written to
  1959.  6   0=returns EOF if device is read    12   1=is NoInherit
  1960. 11   1=is network spooler               14   1=date/time not set at close
  1961. 12   1=is NoInherit                     15   1=is remote, 0=is local
  1962.                                              (all other bits=0)
  1963. See: SetRetriesXB  DriveRemoteXB  LockXB
  1964. ~SetRetriesXB
  1965. Pack: SetRetriesPack    Src: SetRetriesXBsrc    Func:  88/Network
  1966. Set the number of times DOS retries disk operations after a failure due to
  1967. file-sharing operations (locked file regions from LockXB routines).
  1968. This routine uses INT21/44/sub function 0Bh.
  1969. By default DOS retries an operation 3 times (without pausing between attempts)
  1970. before returning an error to the application.
  1971. If you change the default values it's recommended that the default state be  
  1972. restored before your application ends (Retries=3, Pause=1).                  
  1973. These values are pretty much determined by trial-and-error. You may find that
  1974. adding a delay between retries returns fewer access-denied errors, but on
  1975. current machines, the delay is in the few millisecond range, tops.
  1976. See: DeleteFileDOS  LockXB
  1977. ~DeleteFileDOS
  1978. Pack: DOSFilePack       Src: DeleteFileDOSsrc   Func: 100/DOS
  1979. Delete the specified file.
  1980. This routine uses DOS INT21/41 (interrupt 21h function 41h).
  1981. See: RenameFileDOS
  1982. ~RenameFileDOS
  1983. Pack: DOSFilePack       Src: RenameFileDOSsrc   Func: 101/DOS
  1984. Rename a file. May also be used to move the file to a new directory within the
  1985. partition.
  1986. This routine uses DOS INT21/56.
  1987. If the specified directory differs from the file's directory, the file's     
  1988. directory entry is moved to the new directory.                               
  1989. For example, if the FilenamePtr filename is C:\LP100\PROJ93A.INF and the
  1990. NewFilenamePtr filename is C:\ARCH\PROJ93A.INA, the file is essentially
  1991. renamed and also moved to the \ARCH directory.
  1992. See: CreateFileDOS
  1993. ~CreateFileDOS
  1994. Pack: DOSFilePack       Src: CreateFileDOSsrc   Func: 102/DOS
  1995. Create a new file.
  1996. This routine uses INT21/3C.
  1997. The specified filename/pathname must NOT already exist.
  1998. The file created is not left open. You must OpenFileDOS to use it.
  1999. The attribute used during the create can be:
  2000.   ATTRIBUTE       VALUE    MEANING
  2001.    Normal              0    normal access permitted to file
  2002.    Read-Only           1    read-only access permitted to file
  2003.    Hidden              2    file does not appear in directory listing
  2004.    System              4    file is a system file
  2005.    Volume              8    FILENAME used as volume label if no current label
  2006.    Archive            20h   file is marked for archiving
  2007. See: AccessFileDOS  OpenFileDOS
  2008. ~AccessFileDOS
  2009. Pack: DOSFilePack       Src: AccessFileDOSsrc   Func: 103/DOS
  2010. Determine if the specified file can be accessed with the specified
  2011. access/sharing mode.
  2012. This routine uses INT21/3D and INT21/3E.
  2013. Basically, a Does-File-Exist routine. It uses the specified access/sharing
  2014. attributes when trying to open the file. For example, if you specify
  2015. DFP.Attr = &H42 (R/W access + Deny None sharing) and use AccessFileDOS on a
  2016. Read-Only DOS file, the return value would be DOS error 5, Access Denied.
  2017. See: OpenFileDOS
  2018. ~OpenFileDOS
  2019. Pack: DOSFilePack       Src: OpenFileDOSsrc     Func: 104/DOS
  2020. Open the specified file with the specified access/sharing mode.
  2021. This routine uses INT21/3D.
  2022.   ACCESS          VALUE    MEANING
  2023.    Read-only           0    open for read-only access
  2024.    Write-only          1    open for write-only access
  2025.    Read/Write          2    open for read/write access
  2026.   SHARE
  2027.    Compatibility       0     any process may share file (not recommended)
  2028.    Deny Read/Write    10h    no other process may share file
  2029.    Deny Write         20h    no other process may share file for write
  2030.    Deny Read          30h    no other process may share file for read
  2031.    Deny None          40h    any process may share file except in Compatibilty
  2032.   INHERIT                                                                 mode
  2033.    NoInheritFlag      80h    if set child processes do not inherit file handles
  2034.                              (child process cannot inherit handle > 20)
  2035. The file access mode is a combination of ACCESS + SHARE + INHERIT.
  2036. See: SeekFileDOS  OpenPack
  2037. ~SeekFileDOS
  2038. Pack: DOSFilePack       Src: SeekFileDOSsrc     Func: 105/DOS
  2039. Position the DOS file pointer of the specified file to the specified position.
  2040. This routine uses INT21/42.
  2041. The position is a 32-bit value and is relative to either the start of the file,
  2042. the current file pointer position, or the end of the file.
  2043.  Method  Meaning
  2044.     0    start move from the start of file (offset is a 32-bit unsigned value)
  2045.     1    start move at the current position (offset a signed value)
  2046.     2    start move at the end of file (offset a signed value)
  2047. For example, to move to the 511th byte of a file (byte 0 being the first), set
  2048. the offset value to 511 and use Method 0. On return, the absolute offset value
  2049. of the new position is returned. This is useful with Method 2 since you can
  2050. specify an offset of 0 and have the file length returned.
  2051. Never position the file pointer to before the start of file.                 
  2052. See: ReadFileDOS
  2053. ~ReadFileDOS
  2054. Pack: DOSFilePack       Src: ReadFileDOSsrc     Func: 106/DOS
  2055. Read from the file or device the specified number of bytes into a buffer.
  2056. This routine uses INT21/3F.
  2057. On block devices (such as disks) input starts at the current file position and
  2058. the file pointer is repositioned to the last byte read +1.
  2059. It is possible to read less than the bytes specified without an error being  
  2060. generated. Compare the bytes to read with the returned bytes read value. If  
  2061. less then end of file was reached during the read, if 0 then file was at EOF.
  2062. By using DOS's predefined handles you can read from the keyboard (STDIN) by
  2063. using the STDIN handle, 0. The input will terminate after all specified bytes
  2064. have been read or after a CR (ASCII 0Dh). If more bytes are entered than were
  2065. requested, the next read will retrieve those excess bytes. Therefore, it's
  2066. suggested that you specify 129 bytes to input (DOS will process 127+CR/LF bytes
  2067. maximum when reading the STDIN device). Post-process the entered data by
  2068. scanning for the CR/LF.
  2069. See: ExpandFileDOS
  2070. ~ExpandFileDOS
  2071. Pack: DOSFilePack       Src: ExpandFileDOSsrc   Func: 107/DOS
  2072. Expands the specified file by the specified number of bytes.
  2073. This routine uses INT21/42 and INT21/40.
  2074. This routine is useful in pre-allocating disk space. By reserving disk space in
  2075. advance you can guarantee that enough disk space will be available for a future
  2076. operation (especially if more than 1 process is running). You'll also be able
  2077. ensure that the disk space that a file does use is as contiguous as possible.
  2078. Database systems are dynamic and their files typically allocate new space on
  2079. an as-needed basis. This dynamic allocation can cause parts of a file to be
  2080. located throughout the disk system, possibly affecting performance drastically.
  2081. By pre-allocating the disk space you can be assured of consistent throughput
  2082. performance since the file is contiguous.
  2083. See: WriteFileDOS
  2084. ~WriteFileDOS
  2085. Pack: DOSFilePack       Src: WriteFileDOSsrc    Func: 108/DOS
  2086. Write to the file or device the specified number of bytes from a buffer.
  2087. This routine uses INT21/40.
  2088. If the number of bytes written is less than the specified bytes, this routine
  2089. returns a -2 error code (or 65554 unsigned).                                 
  2090. On block devices (such as disk) output starts at the current file position, and
  2091. the file pointer is repositioned to the last byte written +1.
  2092. If the specified bytes to write is 0, the file is truncated at the current   
  2093. file pointer position.                                                       
  2094. By using DOS's predefined handles you can write to the screen (STDOUT) by
  2095. using the STDOUT handle, 1.
  2096. See: CloseFileDOS
  2097. ~CloseFileDOS
  2098. Pack: DOSFilePack       Src: CloseFileDOSsrc    Func: 109/DOS
  2099. Close the file flushing any internal buffers, releasing any locked regions, and
  2100. update the directory entry to the correct size, date, and time.
  2101. This routine uses INT21/3E.
  2102. If you have opened a file using the DOS open routine you should close it when
  2103. you no longer need it.
  2104. This routine can be used to close the predefined DOS handles (0-4) and make  
  2105. those handles available for reuse. Typically handles 0 and 1 should not be   
  2106. closed by an application since they are the STDIN and STDOUT that DOS uses   
  2107. for the current application (keyboard and screen).                           
  2108. Since BULLET provides for up to 250 user file handles for your applications it
  2109. isn't necessary for you to eek 3 more file handles by closing handles 2-4.
  2110. See: MakeDirDOS
  2111. ~MakeDirDOS
  2112. Pack: DOSFilePack       Src: MakeDirDOSsrc      Func: 110/DOS
  2113. Create a new subdirectory.
  2114. This routine uses INT21/39.
  2115. See: DeleteFileDOS
  2116. ~AccessPack
  2117.  Src: InsertXBsrc      Func: InsertXB and many more
  2118. struct AccessPack {  /* AP (AP is recommended pack name)
  2119.  unsigned  func;     /* varies                 >>>>> REFER to -BULLET.H- <<<<<
  2120.  unsigned  rstat;    /* ret:completion status      for current structure names
  2121.  unsigned  handle;   /* OS handle
  2122.  long      recNo;    /* in:rec# to get/delete/update (if applicable)
  2123.                      /* in:set to single rec# to lock or 0=lock all
  2124.                      /* ret:record number of data record accessed
  2125.  void  far *recPtr;  /* far pointer to record storage buffer
  2126.  void  far *keyPtr;  /* far pointer to search key buffer
  2127.  void  far *nextPtr; /* far pointer to next key access pack
  2128. }; /* 22 */          /* or 0:0 if end of link or if N/A
  2129. The NextPtr variables are only used by InsertXB, UpdateXB, ReindexXB, and the
  2130. LockXB routines. NextPtr is used as a link to the next related access pack,
  2131. if any. Not all entries are used by all routines. Generally, any routine that
  2132. gets/puts user data to the database uses this pack.
  2133. Note: Due to space limitations all comments should be assumed to be terminated
  2134. on the same line (implicit */).
  2135. See: BreakPack
  2136. ~BreakPack
  2137.  Src: BreakXBsrc       Func: BreakXB
  2138. struct BreakPack { /* BP
  2139.  unsigned  func;   /* 4
  2140.  unsigned  rstat;  /* ret:completion status
  2141.  unsigned  mode;   /* =0 disable Ctrl-C/Ctrl-Break, 1=restore
  2142. }; /* 6 */
  2143. A simple pack.
  2144. See: CopyPack
  2145. ~CopyPack
  2146.  Src: BackupFileXBsrc  Func: BackupFileXB, CopyDHXB, CopyKHXB
  2147. struct CopyPack {        /* CP
  2148.  unsigned  func;         /* 5=BackupFileXB,16=CopyDHXB,26=CopyKHXB
  2149.  unsigned  rstat;        /* ret:completion status
  2150.  unsigned  handle;       /* handle of BULLET file
  2151.  char far *filenamePtr;  /* far pointer to filenameZ
  2152. }; /* 10 */
  2153. See: CreateDataPack
  2154. ~CreateDataPack
  2155.  Src: CreateDXBsrc     Func: CreateDXB
  2156. struct CreateDataPack { /* CDP
  2157.  unsigned  func;        /* 10
  2158.  unsigned  rstat;       /* ret:completion status
  2159.  char far *filenamePtr; /* far pointer to filenameZ to create
  2160.  unsigned  noFields;    /* number of fields per record
  2161.  void far *fieldListPtr;/* far pointer to field list
  2162.  unsigned  fileID;      /* file signature byte, usually=3
  2163. }; /* 16 */
  2164. The FieldListPtr variables point to an array of struct fieldDescType. This
  2165. array is dimensioned for as many fields as there are in the record and contains
  2166. the field descriptors, one for each field.
  2167. See: CreateKeyPack  FieldDescType
  2168. ~CreateKeyPack
  2169.  Src: CreateKXBsrc     Func: CreateKXB
  2170. struct CreateKeyPack { /* CKP
  2171.  unsigned  func;       /* 20
  2172.  unsigned  rstat;      /* ret:completion status
  2173.  char far *filenamePtr;/* far pointer to filenameZ
  2174.  char far *keyExpPtr;  /* far pointer to key expressionZ
  2175.  unsigned  xbLink;     /* BULLET XB data handle this file indexes
  2176.  unsigned  keyFlags;   /* bit 0=unique,1=char,4=int,5=lng,F=signed
  2177.  int       codePageID; /* codepage for NLS, -1 use system default
  2178.  int       countryCode;/* country code for NLS, -1 to use default
  2179.  char far *collatePtr; /* far ptr to prg-supplied collate table
  2180. }; /* 24 */            /* or 0:0 if using sys-determined NLS table
  2181. Bit 14 in KeyFlags (0Eh) is set by BULLET during CreateKXB if a collate table
  2182. is present.
  2183. See: DescriptorPack  is_NLS
  2184. ~DescriptorPack
  2185.  Src: GetDescriptorXBsrc  Func: GetDescriptorXB
  2186. struct DescriptorPack {   /* DP
  2187.  unsigned  func;          /* 30
  2188.  unsigned  rstat;         /* ret:completion status
  2189.  unsigned  handle;        /* BULLET data file handle to get info on
  2190.  unsigned  fieldNumber;   /* field number to get info on, or if 0...
  2191.  struct fieldDescType fd; /* ...search for DP.FD.fieldName
  2192. }; /* 40 */
  2193. GetDescriptorXB allows you to get the field descriptor info for a particular
  2194. field number (as in the first field, or the 10th field, etc.) or, if you don't
  2195. know the physical field number, the routine can also get the info for a field
  2196. by field name.
  2197. To get the info for field number, say 5, set DP.FieldNumber = 5. The DP.FD
  2198. structure element is filled in with field 5's information.
  2199. To get the info for a field by fieldname, say LASTNAME, set dp.fieldnumber=0 &
  2200. strcpy(dp.fd.fieldname, "LASTNAME\0\0\0")--the fieldname must be zero-filled
  2201. and zero-terminated.
  2202. See: DOSFilePack  FieldDescType
  2203. ~DOSFilePack
  2204.  Src: AccessFileDOSsrc  Func: AccessFileDOS
  2205.                                             (all routines ending with DOS)
  2206. struct DosFilePack {   /* DFP
  2207.  unsigned  func;       /* varies, see DeleteFileDOS for first
  2208.  unsigned  rstat;      /* ret:completion status
  2209.  char far *filenamePtr;/* far pointer to filenameZ
  2210.  unsigned  handle;     /* in: handle to access  ret: handle opened
  2211.  unsigned  asMode;     /* open access/sharing mode
  2212.  unsigned  bytes;      /* in: bytes to read  ret: bytes read
  2213.  long      seekOffset; /* seek to file position
  2214.  unsigned  method;     /* seek method
  2215.  void far *bufferPtr;  /* far pointer to read/write buffer
  2216.  unsigned  attr;       /* file create directory entry attribute
  2217.  char far *newNamePtr; /* far pointer to new filenameZ for rename
  2218. }; /* 30 */
  2219. All of the xDOS routines use this pack. Often only a few of the structure
  2220. member elements are used by any one of the routines. Set only those needed.
  2221. See: DVmonPack
  2222. ~DVmonPack
  2223.  Src: DVmonCXBsrc      Func: DVmonCXB
  2224. struct DVmonPack { /* AVAILABLE ONLY IN THE DEBUG ENGINE
  2225.  unsigned  func;   /* 9
  2226.  unsigned  rstat;  /* ret:completion status
  2227.  unsigned  mode;   /* =0 disable montitoring, =1 enable
  2228.  unsigned  handle; /* file handle to monitor
  2229.  unsigned  vs;     /* segment to write screen image (e.g., 0xB800)
  2230. }; /* 10 */
  2231. This routine is supplied only in the BULLET debug engine. It displays real-time
  2232. monitoring information of a .DBF file or index and .DBF file pair including
  2233. searches, seeks, hits, current record number, current key, key node contents,
  2234. key node pointers, stack state, key and record counts, and other info.
  2235. See: ExitPack
  2236. ~ExitPack
  2237.  Src: InitXBsrc        Func: ExitXB, AtExitXB
  2238. struct ExitPack {  /* EP
  2239.  unsigned  func;   /* 1=ExitXB, 2=AtExitXB
  2240.  unsigned  rstat;  /* ret:completion status
  2241. }; /* 4 */
  2242. See: FieldDescType
  2243. ~FieldDescType
  2244.  Src: CreateDXBsrc     Func: CreateDXB
  2245. struct FieldDescType {   /* used by CreateDataPack ONLY
  2246.  char  fieldName[11];    /* 0-filled (use only ASCII 65-90,95)
  2247.  char  fieldType;        /* C-har,N-umeric,D-ate,L-ogical,M-emo
  2248.  unsigned long fieldDA;  /* =0,reserved
  2249.  unsigned char fieldLen; /* C=1-254,N=1-19(varies),D=8,L=1,M=10
  2250.  unsigned char fieldDC;  /* dec places for FieldType=N (0,2-15)
  2251.  long  fieldRez;         /* =0,reserved
  2252.  char  filler[10];       /* =0,reserved
  2253. }; /* 32 */
  2254. If you can can forgo dBASE compatility you can use the B field type. This type
  2255. is for fields that contain binary data (all dBASE fields contain ASCII text or
  2256. numeric strings). If you specify a fieldType = 'B' for, say an integer field,
  2257. use a FieldLen = 2. If the field is a long integer, use FieldLen = 4. You can
  2258. also use this non-standard field type for indexing. See CreateKXB for more.
  2259. See: HandlePack  CreateDataPack  CreateKXB
  2260. ~HandlePack
  2261.  Src: CloseDXBsrc      Func: CloseDXB, ReadDHXB, FlushDHXB, ZapDHXB
  2262.                              CloseKXB, ReadKHXB, FlushKHXB, ZapKHXB
  2263.                     /* HP
  2264. struct HandlePack { /* 12=CloseDXB,14=ReadDHXB,15=FlushDHXB,17=ZapDH
  2265.  unsigned  func;    /* 22=CloseDXB,24=ReadKHXB,25=FlushKHXB,27=ZapKH
  2266.  unsigned  rstat;   /* ret:completion status
  2267.  unsigned  handle;  /* handle of BULLET file
  2268. }; /* 6 */
  2269. See: InitPack
  2270. ~InitPack
  2271.  Src: InitXBsrc        Func: InitXB
  2272. struct InitPack {       /* IP
  2273.  unsigned  func;        /* 0
  2274.  unsigned  rstat;       /* ret:completion status
  2275.  unsigned  JFTmode;     /* expand JFT if non-zero
  2276.  unsigned  DOSver;      /* ret:DOS version (HB=major, LB=minor)
  2277.  unsigned  OSversion;   /* ret:BULLET OS version
  2278.                         /* (0=DOS, 1=Win16, 2=OS/2-16, 3=OS/2-32) */
  2279.  unsigned  version;     /* ret:BULLET version * 100 (120=1.20)
  2280.  unsigned long exitPtr; /* ret:far pointer to ExitXB routine
  2281. }; /* 14 */
  2282. See: MemoryPack
  2283. ~MemoryPack
  2284.  Src: MemoryXBsrc      Func: MemoryXB
  2285. struct MemoryPack {    /* MP
  2286.  unsigned  func;       /* 3
  2287.  unsigned  rstat;      /* ret:completion status
  2288.  unsigned long memory; /* ret:largest free OS memory block
  2289. See: OpenPack
  2290. ~OpenPack
  2291.  Src: OpenDXBsrc       Func: OpenDXB, OpenKXB
  2292. struct OpenPack {       /* OP
  2293.  unsigned  func;        /* 11=OpenDXB,21=OpenKXB
  2294.  unsigned  rstat;       /* ret:completion status
  2295.  unsigned  handle;      /* ret:OS handle of file opened
  2296.  char far *filenamePtr; /* far pointer to filenameZ to open
  2297.  unsigned  asMode;      /* DOS access-sharing mode(see OpenFileDOS)
  2298.  unsigned  xbLink;      /* if opening index this related data file
  2299. }; /* 14 */             /* (if opening data file xbHandle not used)
  2300. Note: you must supply xbLink on index file opens
  2301. See: RemotePack  OpenFileDOS
  2302. ~RemotePack
  2303.  Src: DriveRemoteXBsrc  Func: DriveRemoteXB, FileRemoteXB
  2304. struct RemotePack {  /* RP
  2305.  unsigned  func;     /* 86=DriveRemoteXB,87=FileRemoteXB
  2306.  unsigned  rstat;    /* ret:completion status
  2307.  unsigned  handle;   /* handle/drive depending on routine
  2308.  unsigned  isRemote; /* ret:0=local,1=remote
  2309.  unsigned  flags;    /* ret:dx register as returned by DOS
  2310.  unsigned  isShare;  /* ret:0=SHARE.EXE not loaded
  2311. }; /* 12 */
  2312. See: SetRetriesPack
  2313. ~SetRetriesPack
  2314.  Src: SetRetriesXBsrc  Func: SetRetriesXB
  2315. struct SetRetriesPack { /* SRP
  2316.  unsigned  func;        /* 88
  2317.  unsigned  rstat;       /* ret:completion status
  2318.  unsigned  mode;        /* 0=set DOS default else Pauses/Retries below
  2319.  unsigned  pause;       /* 0-65535 loop counter between retries
  2320.  unsigned  retries;     /* 0-65535 retries to access locked file
  2321. }; /* 10 */
  2322. The default values for Retries is 3 and Pause is 1.
  2323. The Pause value is used as a simple loop counter used to waste time. This loop
  2324. IS dependent on CPU power so values are not portable across different machines.
  2325. See: StatDataPack
  2326. ~StatDataPack
  2327.  Src: StatDXBsrc       Func: StatDXB
  2328. struct StatDataPack {   /* SDP
  2329.  unsigned  func;        /* 13
  2330.  unsigned  rstat;       /* ret:completion status
  2331.  unsigned  handle;      /* BULLET data file to get status on
  2332.  unsigned char fileType;/* ret:1=BULLET XB data file
  2333.  unsigned char dirty;   /* ret:0=not changed
  2334.  unsigned long recs;    /* ret:records in file
  2335.  unsigned  recLen;      /* ret:record length
  2336.  unsigned  fields;      /* ret:fields per record ()
  2337.  char      f1;          /* reserved (1=update DVmon)
  2338.  unsigned char LUyear;  /* ret:binary, year file last updated
  2339.  unsigned char LUmonth; /* ret:month--LUs are 0 if DBF newly created
  2340.  unsigned char LUday;   /* ret:day
  2341.  unsigned hereSeg;      /* ret:this file's control segment
  2342.  char filler[10];       /* reserved
  2343. }; /* 32 */
  2344. See: StatKeyPack
  2345. ~StatKeyPack
  2346.  Src: StatKXBsrc       Func: StatKXB
  2347. struct StatKeyPack {        /* SKP
  2348.  unsigned  func;            /* 23
  2349.  unsigned  rstat;           /* ret:completion status
  2350.  unsigned  handle;          /* BULLET key file to get status on
  2351.  unsigned  char fileType;   /* ret:0=BULLET XB key file
  2352.  unsigned  char dirty;      /* ret:0=not changed
  2353.  unsigned  long keys;       /* ret:keys in file
  2354.  unsigned  keyLen;          /* ret:key length
  2355.  unsigned  xbLink;          /* ret:related BULLET XB data handle
  2356.  unsigned  long xbRecNo;    /* ret:recno attached to current key
  2357.  unsigned  hereSeg;         /* ret:this file's control segment
  2358.  unsigned  codePageID;      /* ret:codepage of key file sort
  2359.  unsigned  countryCode;     /* ret:countrycode of key file sort
  2360.  unsigned  collateTableSize;/* ret:size of collate table, 0 or 256
  2361.  unsigned  keyFlags;        /* ret:bit 0=unique,1=char,4=int,
  2362.  char filler[2];            /*     5=long,E=NLS,F=signed
  2363. }; /* 32 */
  2364. See: StatHandlePack
  2365. ~StatHandlePack
  2366.  Src: StatHandleXBsrc  Func: StatHandleXB
  2367. struct StatHandlePack { /* SHP
  2368.  unsigned  func;        /* 6
  2369.  unsigned  rstat;       /* ret:completion status
  2370.  unsigned  handle;      /* file handle to get information on
  2371.  unsigned  ID;          /* ret:0=index,1=data,-1=not BULLET handle
  2372.  char far *filenamePtr; /* pointer to filename of handle
  2373. }; /* 12 */
  2374. See: XErrorPack
  2375. ~XErrorPack
  2376.  Src: GetExtErrorXBsrc Func: GetExtErrorXB
  2377. struct XerrorPack {  /* XEP
  2378.  unsigned  func;     /* 7
  2379.  unsigned  rstat;    /* ret:extended error
  2380.  unsigned  class;    /* ret:error class
  2381.  unsigned  action;   /* ret:suggested action
  2382.  unsigned  location; /* ret:error location
  2383. }; /* 10 */
  2384. See: AccessPack  Errors_DOS
  2385. ~Errors_BULLET    (200-209)
  2386. 200 key not found - The search key for Equal was not matched exactly.
  2387.     Next/Prev routines can be used to continue search from point of mismatch.
  2388. 201 key already exists - Attempted to add a key that already exists in the
  2389.     index file created to allow only unique keys.
  2390. 202 end of file - A Next routine is past the last key of the index file.
  2391. 203 top of file - A Prev routine is before the first key of the index file.
  2392. 204 key file empty - A key access was attempted with no keys in the index file.
  2393. 205 key type unknown - Generally indicates a corrupt index header (keyflags
  2394.     unknown at key insert).
  2395.     reserved,206-207
  2396. 208 no more nodes - The index file has reached full capacity (32MB). ReindexXB
  2397.     can often shrink an index file by 30 to 50%.
  2398. 209 key file corrupt - The index file is corrupt (write attempt to node 0).
  2399. See: Errors_BULLET_b
  2400. ~Errors_BULLET_b  (210-232)
  2401. 210 key file corrupt - The index file is corrupt (internal overflow).
  2402.     reserved,211-219
  2403. 220 incorrect DOS version - BULLET requires DOS 3.3 or later.
  2404. 221 invalid key length - The key is > 62 bytes (or 64 if unique specified).
  2405. 222 file not open - The specified handle is not an open BULLET file.
  2406.        
  2407.     reserved,223
  2408. 224 invalid record number - The specified record number is < 0, past the last
  2409.     record number in the .DBF, or is > 16,777,215.
  2410.     reserved,225-227
  2411. 228 invalid filetype - The specified handle is not the correct type for the
  2412.     operation (i.e., specifying a data file handle for a key file operation).
  2413.     reserved,229-232
  2414. See: Errors_BULLET_c
  2415. ~Errors_BULLET_c  (233-243)
  2416. 233 init not active - InitXB must be called before all others except MemoryXB.
  2417. 234 init already active - InitXB has already been called. Use ExitXB first to
  2418.     call InitXB more than once per process. (Make sure the xxP.Func <> 0.)
  2419. 235 too many indexes - BULLET can handle up to 32 index files per transaction
  2420.     record with the InsertXB and UpdateXB routines. Contact the author if you
  2421.     need to allow for more than 32 index files/transaction record.
  2422.     reserved,236-239
  2423. 240 invalid key expression - The CreateKXB key expression could not be
  2424.     evaluated.
  2425.     reserved,241
  2426. 242 field not found - The fieldname was not found in the descriptor area.
  2427. 243 invalid field count - Too many fields were specified or the specified field
  2428.     number is past the last field.
  2429. See: Errors_BULLET_d
  2430. ~Errors_BULLET_d  (244-255)
  2431.     reserved,244-247
  2432. 250 invalid country info - The specifed country code or code page ID is not
  2433.     valid or not installed (according to DOS).  Also 248 and 249.
  2434. 251 invalid collate table size - The specified country code/code page ID uses
  2435.     a collate-sequence table > 256 bytes (2-byte characters as with Kanji).
  2436. 252 invalid keyflags - The specified keyflags are invalid.
  2437.     reserved,253-254
  2438. 255 evaluation mode shutdown - BULLET evaluation period has completed.
  2439.     You can reinstall to continue evaluation, though you may want to consider
  2440.     your motives for reinstalling since the original evaluation period has
  2441.     expired. This error occurs only after the evaluation period has expired.
  2442.     It is not recommended that you continue to use BULLET after the evaluation
  2443.     period. It is possible for no 255 error to be generated for quite some
  2444.     time since it occurs only under certain load conditions and then only when
  2445.     certain routine sequences are performed. The specified evaluation period of
  2446.     21 days should be adhered to.
  2447. See: Errors_DOS
  2448. ~Errors_DOS
  2449. -2 disk full or unexpected end of file (65534)
  2450. -1 bad filename (65535)
  2451.  0 no error
  2452.  1 function not supported              19 disk write protected
  2453.  2 file not found                      20 unknown unit
  2454.  3 path not found                      21 drive not ready
  2455.  4 too many open files                 22 unknown command
  2456.  5 access denied (see Specs_Networks)  23 data error (CRC)
  2457.  6 handle invalid                      24 bad request structure length
  2458.  7 MCBs destroyed                      25 seek error
  2459.  8 not enough memory                   26 unknown medium type
  2460.  9 memory block address invalid        27 sector not found
  2461. 10 environment invalid                 28 printer out of paper
  2462. 11 format invalid                      29 write fault
  2463. 12 access code invalid                 30 read fault
  2464. 13 data invalid                        31 general failure
  2465.    reserved-0Eh                        32 sharing violation
  2466. 15 disk drive invalid                  33 lock violation
  2467. 16 cannot remove current directory     34 disk change invalid/wrong disk
  2468. 17 not same device                     35 FCB unavailable
  2469. 18 no more files                       36 sharing buffer overflow
  2470. See: Errors_DOS_b
  2471. ~Errors_DOS_b
  2472. 37 code page mismatched                58 incorrect response from network
  2473. 38 handle EOF                          59 unexpected network error
  2474. 39 handle disk full                    60 incompatible remote adapter
  2475.    reserved-28h                        61 print queue full
  2476.    reserved-29h                        62 no spool space
  2477.    reserved-2Ah                        63 not enough space to print file
  2478.    reserved-2Bh                        64 network name deleted
  2479.    reserved-2Ch                        65 network access denied
  2480.    reserved-2Dh                        66 network device type incorrect
  2481.    reserved-2Eh                        67 network name not found
  2482.    reserved-2Fh                        68 network name limit exceeded
  2483.    reserved-30h                        69 NETBIOS session limit exceeded
  2484.    reserved-31h                        70 sharing temporarily paused
  2485. 50 network request not supported       71 network request not accepted
  2486. 51 remote computer not listening       72 print/disk redirection paused
  2487. 52 duplicate name on network              reserved-49h
  2488. 53 network pathname not found             reserved-4Ah
  2489. 54 network busy                           reserved-4Bh
  2490. 55 network device no longer exists        reserved-4Ch
  2491. 56 NETBIOS command limit exceeded         reserved-4Dh
  2492. 57 network adapter hardware error         reserved-4Eh
  2493. See: Errors_DOS_c
  2494. ~Errors_DOS_c
  2495.    reserved-4Fh                  
  2496.  DOS Class Codes 
  2497. 80 file exists
  2498. 81 duplicate FCB                 1 out of resources       7 application error
  2499. 82 cannot make                   2 temporary situation    8 not found
  2500. 83 fail on INT24                 3 authorization          9 bad format
  2501. 84 out of structures             4 internal error        10 locked
  2502. 85 already assigned              5 hardware failure      11 media failure
  2503. 86 invalid password              6 system failure        12 already exists
  2504. 87 invalid parameter                                     13 unknown
  2505. 88 network write fault
  2506.    reserved-59h                    DOS Action Codes         DOS Locus Codes
  2507. 90 sys comp not loaded
  2508.                                  1 retry immediately      1 unknown
  2509.                                  2 delay and retry        2 block device
  2510.                                  3 reenter input          3 network
  2511.                                  4 abort ASAP             4 serial device
  2512.                                  5 abort immediately      5 memory
  2513.                                  6 ignore error
  2514.                                  7 user intervention
  2515. See: Errors_BULLET
  2516. ~InitXBsrc
  2517. Func: InitXB           Pack: InitPack           Func:   0/System
  2518. struct InitPack IP;
  2519. struct ExitPack EP;
  2520. IP.func = INITXB;       /* InitXB defined in BULLET.H
  2521. IP.JFTmode = 1;         /* expand JFT to 255 handles
  2522. rstat = BULLET(&IP);
  2523. if (rstat == 0) {
  2524.    EP.func = ATEXITXB;  /* register ExitXB with _atexit shutdown routine
  2525.    rstat = BULLET(&EP);
  2526. if (rstat != 0) /*error
  2527. Note: Due to space limitations all comments should be assumed to be terminated
  2528. on the same line (implicit */). Right.
  2529. See: ExitXBsrc
  2530. ~ExitXBsrc
  2531. Func: ExitXB           Pack: ExitPack           Func:   1/System
  2532. struct ExitPack EP;
  2533. EP.func = EXITXB      /* ExitXB defined in BULLET.H
  2534. rstat = BULLET(&EP)
  2535. The return value from ExitXB is currently always 0.
  2536. See: AtExitXBsrc
  2537. ~AtExitXBsrc
  2538. Func: AtExitXB         Pack: ExitPack           Func:   2/System
  2539. struct InitPack IP;
  2540. struct ExitPack EP;
  2541. IP.func = INITXB;       /* InitXB defined in BULLET.H
  2542. IP.JFTmode = 1;         /* expand JFT to 255 handles
  2543. rstat = BULLET(&IP);
  2544. if (rstat == 0) {
  2545.    EP.func = ATEXITXB;  /* register ExitXB with _atexit shutdown routine
  2546.    rstat = BULLET(&EP);
  2547. if (rstat != 0)  /* error
  2548. See: MemoryXBsrc
  2549. ~MemoryXBsrc
  2550. Func: MemoryXB         Pack: MemoryPack         Func:   3/System
  2551. struct MemoryPack MP;
  2552. MP.func = MEMORYXB;
  2553. rstat = BULLET(&MP);
  2554. /* MP.memory = amount of far heap available */
  2555. MP.memory does not reflect memory available through DOS in the UMB area. It's
  2556. possible that all memory requests can be satisfied by UMB RAM. Consult a DOS 5+
  2557. programmer reference for more information on this (see DOS INT21/58 for more).
  2558. See: BreakXBsrc
  2559. ~BreakXBsrc
  2560. Func: BreakXB          Pack: BreakPack          Func:   4/System
  2561. struct BreakPack BP;
  2562. BP.func = BREAKXB;    /* BreakXB defined in BULLET.H
  2563. BP.mode = 0;          /* disable Ctrl-C/Ctrl-BREAK (do nothing on those keys)
  2564. rstat = BULLET(&BP);  /* rstat=0 always
  2565. If BreakXB is called multiple times with the same BP.mode each time, only the
  2566. first is acted on. You can set BP.mode = 1 to restore the default handlers
  2567. (those installed originally) and then again set BP.Mode = 0 to disable them.
  2568. ExitXB calls this routine automatically as part of the BULLET shutdown to
  2569. restore the original default break handlers.
  2570. See: BackupFileXBsrc
  2571. ~BackupFileXBsrc
  2572. Func: BackupFileXB     Pack: CopyPack           Func:   5/System
  2573. struct AccessPack AP;
  2574. struct CopyPack CP;
  2575. CP.func = BACKUPFILEXB;         /* defined in BULLET.H
  2576. CP.handle = dataHandle;         /* handle of data file to backup
  2577. CP.filenamePtr = newFilename;   /* filename to save to
  2578. rstat = BULLET(&CP);
  2579. if (rstat == 0) {
  2580.    AP.func = PACKRECORDSXB;
  2581.    AP.handle = dataHandle;
  2582.    rstat = BULLET(&AP);
  2583. IF (rstat != 0) ... /* error
  2584. See: StatHandleXBsrc
  2585. ~StatHandleXBsrc
  2586. Func: StatHandleXB     Pack: StatHandlePack     Func:   6/System
  2587. struct StatHandlePack SHP;
  2588. struct StatKeyPack SKP;
  2589. struct StatDataPack SDP;
  2590. SHP.func = STATHANDLEXB;        /* defined in BULLET.H
  2591. SHP.handle = theHandleNumber;
  2592. rstat = BULLET(&SHP);
  2593. if (SHP.ID == 0) {     /* handle belongs to an index file (index file/key file)
  2594.    SKP.func = STATKXB; /* get key stats  -- see StatKXB/StatDXB for more
  2595.    SKP.handle = passedHandleNumber;     /* on the SKP structure
  2596.    rstat = BULLET(&SKP);
  2597. elseif (SHP.ID == 1) {   /*.DBF data file
  2598.    /* get DBF stats
  2599.    /* error not a BULLET file type
  2600. See: GetExtErrorXBsrc
  2601. ~GetExtErrorXBsrc
  2602. Func: GetExtErrorXB    Pack: XErrorPack         Func:   7/System
  2603. /* an error just occured in the range 1 to 199 as returned in one of the
  2604. /* pack.stat variables (current max DOS error is 90 (5Ah))
  2605. /* remember, transaction-based routines return a bad pack index in the return
  2606. /* rstat value, which you use to check the appropriate pack.Stat variable
  2607. struct XerrorPack XEP;
  2608. XEP.func = GETEXTERRORXB;       /* defined in BULLET.H
  2609. rstat = BULLET(&XEP);
  2610. if (rstat != 0) {
  2611.    /*             error=XEP.rstat
  2612.    /*       error class=XEP.class
  2613.    /* recommened action=XEP.action
  2614.    /*          location=XEP.location
  2615. See: DVmonCXBsrc  StatKXB
  2616. ~DVmonCXBsrc
  2617. Func: DVmonCXB         Pack: DVmonPack          Func:   9/DEBUG
  2618. /* at this point a data file and a key file have been opened
  2619. /* kf is that key file's DOS handle
  2620. struct DVmonPack DVP;
  2621. DV.func = DVMONCXB;     /* defined in BULLET.H
  2622. DV.mode = 1;            /* enable monitoring
  2623. DV.handle = kf;         /* monitor key file handle, kf (and its XBlink file)
  2624. DV.videoSeg = 0xB800+(4096/16);/* output to color screen, page 1 (pages 0 to ?)
  2625. rstat = BULLET(&DV);    /* rstat=0 always even if not DEBUG ENGINE
  2626. For two-monitor systems (with a color monitor as the main system) output should
  2627. be directed to 0xB000, the mono monitor's video memory.
  2628. DVmonCXB stands for Dual Video Monitor Control XB. This module is available
  2629. on the BBS in the BULLET conference files. It is not included in the
  2630. distribution.
  2631. See: CreateDXBsrc
  2632. ~CreateDXBsrc
  2633. Func: CreateDXB        Pack: CreateDataPack     Func:  10/Mid-level
  2634. struct CreateDataPack CDP;
  2635. struct FieldDescType fieldList[2]; /* fld descriptions for each of the fields..
  2636.                                    /* ...in the record (record has 2 fields)
  2637. /* build FD first for each of the fields in the record
  2638. strcpy(fieldlist[0].fieldName, "STUDENT\0\0\0");
  2639. fieldlist[0].fieldType = 'C';
  2640. fieldlist[0].fieldLen = 20;
  2641. fieldlist[0].fieldDC = 0;
  2642. strcpy(fieldlist[1].fieldName, "SCORE\0\0\0\0\0");
  2643. fieldlist[1].fieldType = 'N';
  2644. fieldlist[1].fieldLen = 3;
  2645. fieldlist[1].fieldDC = 0;
  2646. /* (cont)
  2647.                      (for BINARY FieldType="B" see FieldDescType)
  2648. See: CreateDXBsrc_a                                                     -MORE-
  2649. ~CreateDXBsrc_a
  2650. /* build the CDP
  2651. CDP.func = CREATEDXB;           /* defined in BULLET.H
  2652. CDP.filenamePtr = filename;     /* filenameZ (Z=0-terminated str)
  2653. CDP.noFields = 2;               /* this example has 2 fields
  2654. CDP.fieldListPtr = fieldList    /* point to the first field decription...
  2655. CDP.fileID = 3;                 /* standard dBASE file ID
  2656. rstat = BULLET(&CDP);           /* create the DBF data file
  2657. if (rstat !=0) ... /* error
  2658. Normally this code would be written as a generalized FUNCTION. The CDP could be
  2659. a global allocation and the fieldlist would also.
  2660. BULLET can be customized very easily and with very little overhead. If you
  2661. don't like the default API, just develop your own using your own parameter
  2662. order, etc.
  2663. See: OpenDXBsrc  CreateDXBsrc
  2664. ~OpenDXBsrc
  2665. Func: OpenDXB          Pack: OpenPack           Func:  11/Mid-level
  2666. struct OpenPack OP;
  2667. OP.func = OPENDXB;                /* defined in BULLET.H
  2668. OP.filenamePtr = filename;        /* file to open (must already exist)
  2669. OP.asMode = ReadWrite | DenyNone; /* defined in BULLET.H
  2670. rstat = BULLET(&OP);
  2671. if (rstat !=0) ... /* error
  2672. The asMode (access/sharing mode) determines how the operating system controls
  2673. access to the file. See OpenFileDOS for the meanings of the various ASmodes.
  2674. See: CloseDXBsrc  OpenFileDOS
  2675. ~CloseDXBsrc
  2676. Func: CloseDXB         Pack: HandlePack         Func:  12/Mid-level
  2677. struct HandlePack HP;
  2678. HP.func = CLOSEDXB;           /* defined in BULLET.H
  2679. HP.handle = dataHandle;       /* handle of the file to close
  2680. rstat = BULLET(&HP);
  2681. if (rstat !=0) ... /* error
  2682. See: StatDXBsrc
  2683. ~StatDXBsrc
  2684. Func: StatDXB          Pack: StatDataPack       Func:  13/Mid-level
  2685. struct StatDataPack SDP;
  2686. SDP.func = STATDXB;        /* defined in BULLET.H
  2687. SDP.handle = dataHandle;   /* data handle to get stats on
  2688. rstat = BULLET(&SDP);      /* must be a data handle, use StatHandleXB if you...
  2689. if (rstat == 0) {          /* ...don't know the type of file a handle's for
  2690.    /* SDP.fileType is set to 1
  2691.    /* SDP.dirty is set to 1 if the file has changed (0=not changed)
  2692.    /* SDP.recs = number of records in the DBF file
  2693.    /* SDP.recLen = record length
  2694.    /* SDP.fields = number of fields in the record
  2695.    /* SDP.f1 is reserved
  2696.    /* SDP.LUyear = year file last updated, binary (year = ASC(SDP.LUyear))
  2697.    /* SDP.LUmonth = month, binary
  2698.    /* SDP.LUday = day, binary
  2699.    /* SDP.hereSeg is set to this handle's control segment (location in memory)
  2700. See: ReadDHXBsrc
  2701. ~ReadDHXBsrc
  2702. Func: ReadDHXB         Pack: HandlePack         Func:  14/Mid-level
  2703. struct HandlePack HP;
  2704. HP.func = READDHXB;          /* defined in BULLET.H
  2705. HP.handle = dataHandle;      /* handle of file whose header you want to reload
  2706. rstat = BULLET(&HP);
  2707. if (rstat != 0) ... /* error
  2708. This routine is automatically called by the network lock routines.
  2709. See: FlushDHXBsrc  LockDataXB
  2710. ~FlushDHXBsrc
  2711. Func: FlushDHXB        Pack: HandlePack         Func:  15/Mid-level
  2712. struct HandlePack HP;
  2713. HP.func = FLUSHDHXB;          /* defined in BULLET.H
  2714. HP.handle = dataHandle;       /* handle of file you want to flush
  2715. rstat = BULLET(&HP);
  2716. if (rstat != 0) ... /* error
  2717. Note that the physical write to disk is performed only if the file has changed
  2718. since the open or last flush.
  2719. This routine is automatically called by the network unlock routines.
  2720. See: CopyDHXBsrc  UnlockDataXB
  2721. ~CopyDHXBsrc
  2722. Func: CopyDHXBsrc      Pack: CopyPack           Func:  16/Mid-level
  2723. struct CopyPack CP;
  2724. CP.func = COPYDHXB;           /* defined in BULLET.H
  2725. CP.handle = dataHandle;       /* handle of file to copy from (the source)
  2726. CP.filenamePtr = filename;    /* far pointer to filenameZ for copy (dest)
  2727. rstat = BULLET(&CP);
  2728. if (rstat !=0) ... /* error
  2729. See: ZapDHXBsrc
  2730. ~ZapDHXBsrc
  2731. Func: ZapDHXB          Pack: HandlePack         Func:  17/Mid-level
  2732. struct HandlePack HP;
  2733. HP.func = ZAPDHXB;            /* defined in BULLET.H
  2734. HP.handle = dataHandle;       /* handle of file you want !ZAP!
  2735. rstat = BULLET(&HP);
  2736. if (rstat !=0)... /* error
  2737. Note that this removes ALL data records from the data file.
  2738. See: CreateKXBsrc
  2739. ~CreateKXBsrc
  2740. Func: CreateKXB        Pack: CreateKeyPack      Func:  20/Mid-level
  2741. /* This code assumes that the datafile was created as in CreateDXBsrc, and that
  2742. /* the datafile was opened as in OpenDXBsrc.
  2743. strcpy(keyEpression,"SUBSTR(STUDENT,1,5)"); /* a non-unique, character key
  2744. struct CreateKeyPack CKP;
  2745. CKP.func = CREATEKXB;           /* defined in BULLET.H
  2746. CKP.filenamePtr = filename;     /* far pointer to filenameZ
  2747. CKP.keyExpPtr = keyExpression;  /* far pointer to key expressionZ
  2748. CKP.xbLink = datahandle;        /* the datafile handle returned from OpenDXB
  2749. CKP.keyFlags = cCHAR;           /* -KEYFLAGS- are defined in BULLET.H
  2750. CKP.codePageID = -1;            /* use DOS default code page ID
  2751. CKP.countryCode = -1;           /* use DOS default country code
  2752. CKP.collatePtrOff = 0;          /* no user-supplied collate table...
  2753. CKP.collatePtrSeg = 0;          /* ...
  2754. rstat = BULLET(&CKP);
  2755. IF (rstat !=0) ... /* error
  2756. Normally this code would be written as a generalized FUNCTION.
  2757. See: OpenKXBsrc  CreateKXBsrc
  2758. ~OpenKXBsrc
  2759. Func: OpenKXB          Pack: OpenPack           Func:  21/Mid-level
  2760. struct OpenPack OP;
  2761. OP.func = OPENKXB;               /* defined in BULLET.H
  2762. OP.filenamePtr = filename;       /* point to filenameZ (Z=0-terminated str)
  2763. OP.asMode = ReadWrite | DenyNone;/* defined in BULLET.H
  2764. OP.xbLink = dataFileHandle;      /* OpenKXB needs to know the data file handle
  2765. rstat = BULLET(&OP);
  2766. if (rstat !=0) ... /* error
  2767. The asMode (access/sharing mode) determines how the operating system controls
  2768. access to the file. See OpenFileDOS for the meanings of the various ASmodes.
  2769. Before you can open an index file you must first open its associated data file.
  2770. See: CloseKXBsrc  OpenFileDOS
  2771. ~CloseKXBsrc
  2772. Func: CloseKXB         Pack: HandlePack         Func:  22/Mid-level
  2773. struct HandlePack HP;
  2774. HP.func = CLOSEDXB;           /* defined in BULLET.H
  2775. HP.handle = indexhandle;      /* handle of the file to close
  2776. rstat = BULLET(&HP);
  2777. if (rstat !=0) ... /* error
  2778. See: StatKXBsrc
  2779. ~StatKXBsrc
  2780. Func: StatKXB          Pack: StatKeyPack        Func:  23/Mid-level
  2781. struct StatKeyPack SKP;
  2782. SKP.func = STATKXB;       /* defined in BULLET.H
  2783. SKP.handle = indexHandle; /* handle to get stats on
  2784. rstat = BULLET(&SKP);     /* must be index handle, use StatHandleXB if you...
  2785. if (rstat == 0) {         /* ...don't know the type of file a handle's for
  2786.   /* SKP.filetype is set to 0
  2787.   /* SKP.dirty is set to 1 if the file has changed (0=not changed)
  2788.   /* SKP.keys = number of key in the index file (index file=key file)
  2789.   /* SKP.keyLen = physical key length (1-64 bytes)
  2790.   /* SKP.xbLink = datafile handle that this index file is associated with
  2791.   /* SKP.xbRecNo is set to record number associated with last accessed key
  2792.   /* SKP.hereSeg is set to this handle's control segment (location in memory)
  2793.   /* SKP.codePageID returns this index file's permanent code page ID
  2794.   /* SKP.countryCode returns this index file's permanent country code
  2795.   /* SKP.collateTableSize = 0 (no collate table present) or 256 (table present)
  2796.   /* SKP.keyFlags= key flags specifed at CreateKXB (except NLS flag may be set)
  2797. else                                               (NLS flag is bit 14, 0x4000)
  2798.   /* error
  2799. See: ReadKHXBsrc
  2800. ~ReadKHXBsrc
  2801. Func: ReadKHXB         Pack: HandlePack         Func:  24/Mid-level
  2802. struct HandlePack HP;
  2803. HP.func = READKHXB;           /* defined in BULLET.H
  2804. HP.handle = indexHandle;      /* handle of file whose header you want to reload
  2805. rstat = BULLET(&HP);
  2806. if (rstat !=0) ... /* error
  2807. This routine is automatically called by the network lock routines.
  2808. See: FlushKHXBsrc  LockKeyXB
  2809. ~FlushKHXBsrc
  2810. Func: FlushKHXB        Pack: HandlePack         Func:  25/Mid-level
  2811. struct HandlePack HP;
  2812. HP.func = FLUSHKHXB;          /* defined in BULLET.H
  2813. HP.handle = indexHandle;      /* handle of file you want to flush
  2814. rstat = BULLET(&HP);
  2815. if (rstat !=0) ... /* error
  2816. Note that the physical write to disk is performed only if the file has changed
  2817. since the open or last flush.
  2818. This routine is automatically called by the network unlock routines.
  2819. See: CopyKHXBsrc  UnlockKeyXB
  2820. ~CopyKHXBsrc
  2821. Func: CopyKHXBsrc      Pack: CopyPack           Func:  26/Mid-level
  2822. struct CopyPack CP;
  2823. CP.func = COPYKHXB;           /* defined in BULLET.H
  2824. CP.handle = indexHandle;      /* handle of file to copy from (the source)
  2825. CP.filenamePtr = filename;    /* far pointer to filenameZ for copy
  2826. rstat = BULLET(&CP);
  2827. if (rstat !=0) ... /* error
  2828. See: ZapKHXBsrc
  2829. ~ZapKHXBsrc
  2830. Func: ZapKHXB          Pack: HandlePack         Func:  27/Mid-level
  2831. struct HandlePack HP;
  2832. HP.func = ZAPKHXB;              /* defined in BULLET.H
  2833. HP.handle = indexHandle;        /* handle of file you want !ZAP!
  2834. rstat = BULLET(&HP);
  2835. if (rstat !=0) ... /* error
  2836. Note that this removes ALL keys from the index file.
  2837. See: GetDescriptorXBsrc
  2838. ~GetDescriptorXBsrc
  2839. Func: GetDescriptorXB  Pack: DescriptorPack     Func:  30/Mid-level
  2840. struct DesciptorPack DP;
  2841. DP.func = GETDESCRIPTORXB;            /* defined in BULLET.H
  2842. DP.handle = dataHandle;               /* handle of file
  2843. if (fieldnumber > 0) {
  2844.    DP.fieldnumber = fieldnumber;      /* field number to get info on
  2845. else {                                /* or, if 0, then
  2846.    DP.fieldNumber = 0;
  2847.    strcpy(DP.FD.fieldName,fieldName); /* fieldname to get info on
  2848. rstat = BULLET(&DP);
  2849. if rstat == 0 {
  2850.    /* DP.FD.fieldName is set to field name
  2851.    /* DP.FD.fieldType is set to field type
  2852.    /* DP.FD.fieldLen is set to field length
  2853.    /* DP.FD.fieldDC is set to field DC
  2854.    /* error
  2855. See: GetRecordXBsrc
  2856. ~GetRecordXBsrc
  2857. Func: GetRecordXB      Pack: AccessPack         Func:  31/Mid-level
  2858. struct RecType {            /* simple DBF record layout
  2859.         char  tag;      <
  2860.         char  code[5];      
  2861. THE FIRST BYTE OF YOUR RECORD TYPES MUST BE TAG! 
  2862.         char  bday[9];      
  2863. }; /* 15 */
  2864. struct RecType recBuff;     /* record has 2 fields, code/C/4.0, bday/D/8.0
  2865. struct AccessPack AP;
  2866. AP.func = GETRECORDXB;      /* defined in BULLET.H
  2867. AP.handle = dataHandle;     /* handle to get record from
  2868. AP.recNo = recNoToGet;      /* record number to get
  2869. AP.recPtr = recBuff;        /* read record from disk into recbuff
  2870. rstat = BULLET(&AP);
  2871. if (rstat == 0) {
  2872.    /* recbuff.code and .bday set to contents of record number (recnotoget)
  2873.    /* error
  2874. /* Be aware of side effects of using C strings (the \0) within a DBF record */
  2875. See: AddRecordXBsrc
  2876. ~AddRecordXBsrc
  2877. Func: AddRecordXB      Pack: AccessPack         Func:  32/Mid-level
  2878. struct RecType {            /* simple DBF record layout
  2879.         char  tag;      <
  2880.         char  code[5];      
  2881. THE FIRST BYTE OF YOUR RECORD TYPES MUST BE TAG! 
  2882.         char  bday[9];      
  2883. }; /* 15 */
  2884. struct RecType recBuff;     /* record has 2 fields, code/C/4.0, bday/D/8.0
  2885. struct AccessPack AP;
  2886. /* be sure to init the tag field to a space (ASCII 32)
  2887. recBuff.tag = ' ';
  2888. strcpy(recBuff.code,"1234");     /* actually uses 5 bytes with \0 */
  2889. strcpy(recBuff.bday,"19331122"); /* and 9 here */
  2890. AP.func = ADDRECORDXB;      /* defined in BULLET.H
  2891. AP.handle = dataHandle;     /* handle to put record to
  2892. AP.recPtr = recBuff;        /* write recBuff to disk
  2893. rstat = BULLET(&AP);
  2894. if (rstat == 0) {
  2895.    /* AP.recNo set to record number to used by just written record
  2896. See: UpdateRecordXBsrc
  2897. ~UpdateRecordXBsrc
  2898. Func: UpdateRecordXB   Pack: AccessPack         Func:  33/Mid-level
  2899. /* see GetRecordXBsrc for this source example's preliminary code
  2900. AP.func = GETRECORDXB;          /* first get the record to update
  2901. AP.handle = dataHandle;         /* 
  2902. AP.recNo = recNoToGet;          /* 
  2903.  Do NOT use UpdateRecordXB to change   
  2904. AP.recPtr = recBuff;            /* 
  2905.  any field(s) used in a key expression.
  2906. rstat = BULLET(&AP);            /* 
  2907.  Instead use UpdateXB.                 
  2908. if (rstat==0) {                 /* 
  2909.    strcpy(recBuff.dbay,"19591122"); /* change only non-key portions of record
  2910.    AP.func = UPDATERECORDXB;        /* defined in BULLET.H
  2911.    rstat = BULLET(&AP)              /* other AP. values are already set by Get
  2912. if (rstat !=0) ... /* error
  2913. See: DeleteRecordXBsrc  UpdateXB
  2914. ~DeleteRecordXBsrc
  2915. Func: DeleteRecordXB   Pack: AccessPack         Func:  34/Mid-level
  2916. struct AccessPack AP;
  2917. AP.func = DELETERECORDXB;     /* defined in BULLET.H
  2918. AP.handle = dataHandle;       /* handle of record to delete
  2919. AP.recNo = recNoToDelete;     /* to determine which record number any record
  2920. rstat = BULLET(&AP);          /* is, use one of the keyed access routines
  2921. if (rstat !=0) ... /* error
  2922. See: UndeleteRecordsrc (XB)
  2923. ~UndeleteRecordsrc (XB)
  2924. Func: UndeleteRecordXB Pack: AccessPack         Func:  35/Mid-level
  2925. struct AccessPack AP;
  2926. AP.func = UNDELETERECORDXB;   /* defined in BULLET.H
  2927. AP.handle = dataHandle;       /* handle of record to undelete
  2928. AP.recNo = recNoToUndelete;   /* to determine which record number any record
  2929. rstat = BULLET(&AP);          /* is, use one of the keyed access routines
  2930. if (rstat !=0) ... /* error
  2931. See: PackRecordsXBsrc
  2932. ~PackRecordsXBsrc
  2933. Func: PackRecordsXB    Pack: AccessPack         Func:  36/Mid-level
  2934. struct AccessPack AP;
  2935. AP.func = PACKRECORDSXB;      /* defined in BULLET.H
  2936. AP.handle = dataHandle;       /* handle of data file to pack
  2937. rstat = BULLET(&AP);
  2938. if (rstat !=0) ... /* error
  2939. See: FirstKeyXBsrc
  2940. ~FirstKeyXBsrc
  2941. Func: FirstKeyXB       Pack: AccessPack         Func:  40/Mid-level
  2942. struct AccessPack AP;
  2943. AP.func = FIRSTKEYXB;         /* defined in BULLET.H
  2944. AP.handle = indexHandle;      /* handle to index file to access key from
  2945. AP.keyPtr = keyBuffer;        /* far pointer to key buffer
  2946. rstat = BULLET(&AP);
  2947. if (rstat==0) {
  2948.    /* keybuff is filled in with the key (for as many bytes as the key length)
  2949.    /* When using the key returned, be aware that if UNIQUE was NOT specified
  2950.    /* then the enumerator word is attached to the end of the key (the right
  2951.    /* two bytes).
  2952.    /* Also, AP.recNo is set to the record number of the first key in the index.
  2953.    /* error
  2954. See: EqualKeyXBsrc
  2955. ~EqualKeyXBsrc
  2956. Func: EqualKeyXB       Pack: AccessPack         Func:  41/Mid-level
  2957. struct AccessPack AP;
  2958. AP.func = EQUALKEYXB;         /* defined in BULLET.H
  2959. AP.handle = indexHandle;      /* handle to index file to find key from
  2960. AP.keyPtr = keyBuffer;        /* far pointer to key buffer (include enumerator
  2961. rstat = BULLET(&AP);          /* if non-UNQIUE key) (double NULL good start)
  2962. if (rstat==0) {
  2963.    /* the key matched exactly (including enumerator, if present)
  2964.    /* keybuff is NOT ALTERED
  2965.    /* AP.recNo is set to the record number of that key
  2966.    if (rstat == 200) {
  2967.       AP.func = NEXTKEYXB     /* if not found, get following key and check the
  2968.       rstat = BULLET(&AP)     /* key proper (key less the enumerator bytes)
  2969.       if (rstat==0) {         /* (i.e., it may be proper key but enumerator=1)
  2970.          /* see NextKeyXBsrc for continuation
  2971. See: NextKeyXBsrc
  2972. ~NextKeyXBsrc
  2973. Func: NextKeyXB        Pack: AccessPack         Func:  42/Mid-level
  2974. /* see EqualKeyXBsrc for preliminary code
  2975. AP.func = NEXTKEYXB;           /* defined in BULLET.H
  2976. rstat = BULLET(&AP);           /* KEYLEN assumed to equal actual key length...
  2977. if (rstat==0) {                /* ...as returned by StatKXB
  2978.    if (IndexFileIsNotUnique) {
  2979.        if (KeyProperMatchesKeyToFind) {
  2980.           /* found a match to the key proper
  2981. This code example follows up on the EqualKeyXBsrc example. See EqualKeyXB for
  2982. more information on finding partial keys.
  2983. See: PrevKeyXBsrc  EqualKeyXBsrc
  2984. ~PrevKeyXBsrc
  2985. Func: PrevKeyXB        Pack: AccessPack         Func:  43/Mid-level
  2986. struct accesspack AP;
  2987. /* assume code has already executed to locate a key--this code then gets the
  2988. /* key before that one
  2989. AP.func = PREVKEYXB;          /* defined in BULLET.H
  2990. AP.handle = indexHandle;      /* handle to index file to access key from
  2991. AP.keyPtr = keyBuff;          /* far pointer to key buffer
  2992. rstat = BULLET(&AP);
  2993. if (rstat==0) {
  2994.    /* keybuff is filled in with the key (for as many bytes as the key length).
  2995.    /* Also, AP.recno is set to the record number of the key.
  2996.    /* error
  2997. See: LastKeyXBsrc
  2998. ~LastKeyXBsrc
  2999. Func: LastKeyXB        Pack: AccessPack         Func:  44/Mid-level
  3000. struct accesspack AP;
  3001. AP.func = LASTKEYXB;          /* defined in BULLET.H
  3002. AP.handle = indexHandle;      /* handle to index file to access key from
  3003. AP.keyPtr = keyBuff;          /* far pointer to key buffer
  3004. rstat = BULLET(&AP);
  3005. if (rstat==0) {
  3006.    /* keybuff is filled in with the key (for as many bytes as the key length).
  3007.    /* Also, AP.recNo is set to the record number of the last key.
  3008.    /* error
  3009. See: StoreKeyXBsrc
  3010. ~StoreKeyXBsrc
  3011. Func: StoreKeyXB       Pack: AccessPack         Func:  45/Mid-level
  3012. struct AccessPack AP;
  3013. /* Assume record has been added to data file (AddRecordXB, returning recno2use)
  3014. /* and key has been built (BuildKeyXB returning keytoadd[]).
  3015.               
  3016. AP.func = STOREKEYXB;         /* defined in BULLET.H
  3017. AP.handle = indexHandle;      /* handle to index file to insert key into
  3018. AP.recNo = recNoToUse;        /* associate this record number with key
  3019. AP.keyPtr = keyToAdd;         /* far pointer to key buffer
  3020. rstat = BULLET(&AP);
  3021. if (rstat==0) {
  3022.    /* key added
  3023.    if (rstat==201) {
  3024.       /* key already exists, you need to construct a unique enumerator--
  3025.       /* provided file wasn't created for UNIQUE keys...INSTEAD USE InsertXB!
  3026.    else
  3027.       /* other error
  3028. See: DeleteKeyXBsrc  InsertXB
  3029. ~DeleteKeyXBsrc
  3030. Func: DeleteKeyXB      Pack: AccessPack         Func:  46/Mid-level
  3031. struct AccessPack AP;
  3032. AP.func = DELETEKEYXB;         /* defined in BULLET.H
  3033. AP.handle = indexHandle;       /* handle to index file of key to delete
  3034. AP.keyPtr = keyBuffer;         /* far pointer to key buffer (incl enum)
  3035.                                /* (this key is searched for exactly)
  3036. rstat = BULLET(&AP);           /* if exact match found the key is deleted!
  3037. if (rstat==0) {
  3038.    /* key deleted permanently
  3039. if (rstat==200) {
  3040.    /* key as stated was not in the index file--if the index is not UNQIUE then
  3041.    /* you must supply the exact enumerator along with the key proper to delete
  3042.    /* --you can use the CurrentKeyXB routine to obtain the exact current key
  3043.    /* other error
  3044. See: BuildKeyXBsrc
  3045. ~BuildKeyXBsrc
  3046. Func: BuildKeyXB       Pack: AccessPack         Func:  47/Mid-level
  3047. struct AccessPack AP;
  3048. /* Assume record has been built and is ready to be added to the data file. The
  3049. /* record is in the variable recbuff.
  3050. AP.func = BUILDKEYXB;        /* defined in BULLET.H
  3051. AP.handle = indexHandle;     /* handle to index file key is to be built for
  3052. AP.recPtr = recBuff;         /* far pointer to data record buffer
  3053. AP.keyPtr = keyBuff;         /* far pointer to key buffer
  3054. rstat = BULLET(&AP)
  3055. if (rstat==0) {
  3056.    /* key built okay so can do a AddRecordXB followed by a StoreKeyXB
  3057.    /* but, again, InsertXB takes care of all this detail and then some--use it
  3058.    /* error
  3059. See: CurrentKeyXBsrc
  3060. ~CurrentKeyXBsrc
  3061. Func: CurrentKeyXB     Pack: AccessPack         Func:  48/Mid-level
  3062. struct accesspack AP;
  3063. AP.func = CURRENTKEYXB;         /* defined in BULLET.H
  3064. AP.handle = indexHandle;        /* handle to index file
  3065. AP.keyPtr = keyBuff;            /* far pointer to key buffer
  3066. rstat = BULLET(&AP);
  3067. if (rstat==0) {
  3068.    /* keybuff set to current key (valid only for KeyLen bytes)
  3069.    /* Also, AP.recno is set to the record number of the key.
  3070.    /* error
  3071. See: GetFirstXBsrc
  3072. ~GetFirstXBsrc
  3073. Func: GetFirstXB       Pack: AccessPack         Func:  60/High-level
  3074. struct AccessPack AP;
  3075. AP.func = GETFIRSTXB;           /* defined in BULLET.H
  3076. AP.handle = indexHandle;        /* handle to index file to access key from
  3077. AP.recPtr = recBuff;            /* far pointer to record buffer
  3078. AP.keyPtr = keyBuff;            /* far pointer to key buffer
  3079. rstat = BULLET(&AP);
  3080. if (rstat==0) {
  3081.    /* keyBuff is filled in with the key (for as many bytes as the key length)
  3082.    /* recBuff is filled in with the data record
  3083.    /* AP.recNo is set to the record number of the first key in the index.
  3084.    /* error
  3085. See: GetEqualXBsrc
  3086. ~GetEqualXBsrc
  3087. Func: GetEqualXB       Pack: AccessPack         Func:  61/High-level
  3088. struct accesspack AP;
  3089. AP.func = GETEQUALXB;           /* defined in BULLET.H
  3090. AP.handle = indexHandle;        /* handle to index file to access key from
  3091. AP.recPtr = recBuff;            /* far pointer to record buffer
  3092. AP.keyPtr = keyBuff;            /* far pointer to key buffer
  3093. rstat = BULLET(&AP);
  3094. if (rstat==0) {
  3095.    /* recBuff and AP.recNo filled as expected (keyBuff remains the same)
  3096.    if (rstat==200) {
  3097.       AP.func = GETNEXTXB;  /* if not found, can get following key--the next
  3098.       rstat = BULLET(&AP);  /* key would logically follow the key not found
  3099.    else
  3100.       /* error
  3101. See: GetNextXBsrc
  3102. ~GetNextXBsrc
  3103. Func: GetNextXB        Pack: AccessPack         Func:  62/High-level
  3104. struct AccessPack AP;
  3105. AP.func = GETNEXTXB;            /* defined in BULLET.H
  3106. AP.handle = indexHandle;        /* handle to index file to access key from
  3107. AP.recPtr = recBuff;            /* far pointer to record buffer
  3108. AP.keyPtr = keyBuff;            /* far pointer to key buffer
  3109. rstat = BULLET(&AP);
  3110. if (rstat==0) {
  3111.    /* keyBuff is filled in with the next key (as many bytes as the key length)
  3112.    /* recBuff is filled in with the data record
  3113.    /* AP.recNo is set to the record number of the next key in the index
  3114.    /* This key is made the current key so GETNEXTXB again gets next, and so on
  3115.    /* error
  3116. See: GetPrevXBsrc
  3117. ~GetPrevXBsrc
  3118. Func: GetPrevXB        Pack: AccessPack         Func:  63/High-level
  3119. struct accesspack AP;
  3120. AP.func = GETPREVXB;            /* defined in BULLET.H
  3121. AP.handle = indexhandle;        /* handle to index file to access key from
  3122. AP.recPtr = recBuff;            /* far pointer to record buffer
  3123. AP.keyPtr = keyBuff;            /* far pointer to key buffer
  3124. rstat = BULLET(&AP);
  3125. if (rstat==0) {
  3126.    /* keyBuff is filled in with the prev key (as many bytes as the key length)
  3127.    /* recBuff is filled in with the data record
  3128.    /* AP.recNo is set to the record number of the prev key in the index
  3129.    /* This key is made the current key so GETPREVXB again gets prev, and so on
  3130.    /* error
  3131. See: GetLastXBsrc
  3132. ~GetLastXBsrc
  3133. Func: GetLastXB        Pack: AccessPack         Func:  64/High-level
  3134. struct AccessPack AP;
  3135. AP.func = GETLASTXB;            /* defined in BULLET.H
  3136. AP.handle = indexHandle;        /* handle to index file to access key from
  3137. AP.recPtr = recBuff;            /* far pointer to record buffer
  3138. AP.keyPtr = keyBuff;            /* far pointer to key buffer
  3139. rstat = BULLET(&AP);
  3140. if (rstat==0) {
  3141.    /* keyBuff is filled in with the key (for as many bytes as the key length)
  3142.    /* recBuff is filled in with the data record
  3143.    /* AP.recNo is set to the record number of the last key in the index.
  3144.    /* error
  3145. See: InsertXBsrc
  3146. ~InsertXBsrc
  3147. Func: InsertXB         Pack: AccessPack         Func:  65/High-level
  3148. struct AccessPack AP[3];   /* array of 3 access packs, 1 for each index file
  3149.                            /* keyBuff and recBuff previously defined
  3150. for (i=0,i<3,i++) {        /* 3=number of related indexes to maintain
  3151.    AP[i].func = INSERTXB;
  3152.    AP[i].handle = indexHandle[i]; /* each index file's handle
  3153.    AP[i].recPtr = recBuff;
  3154.    AP[i].keyPtr = keyBuff;
  3155.    AP[i].nextPtr = &AP[i+1];    /* point to NEXT access pack
  3156. AP[2].nextPtr = NULL;           /* reset last access pack to end-link value
  3157. rstat = BULLET(&AP);
  3158. if (rstat==0) {                 /* if rstat=0 must still check AP[0].stat
  3159.    if (AP[0].stat != 0) {       /* error when adding data record
  3160.       /* error }
  3161.    trueError = AP[rstat-1].stat; /* returned rstat is array index of bad pack
  3162.                                  /* -1 since C packs are 0 based.
  3163. See: UpdateXBsrc
  3164. ~UpdateXBsrc
  3165. Func: UpdateXB         Pack: AccessPack         Func:  66/High-level
  3166. struct AccessPack AP[3];   /* array of 3 access packs, 1 for each index file
  3167.                            /* keyBuff and recBuff previously defined
  3168. for (i=0,i<3,i++) {        /* 3=number of related indexes to maintain
  3169.    AP[i].func = UPDATEXB;
  3170.    AP[i].handle = indexHandle[i]; /* each index file's handle
  3171.    AP[i].recNo = recordNumberToUpdate; /* the record number to update
  3172.    AP[i].recPtr = recBuff;
  3173.    AP[i].keyPtr = keyBuff;
  3174.    AP[i].nextPtr = &AP[i+1];    /* point to NEXT access pack
  3175. AP[2].nextPtr = NULL;           /* reset last access pack to end-link value
  3176. rstat = BULLET(&AP);
  3177. if (rstat==0) {                 /* if rstat=0 must still check AP[0].stat
  3178.    if (AP[0].stat != 0) {       /* error when adding data record
  3179.       /* error }
  3180.    trueerror = AP[rstat-1].stat; /* returned rstat is array index of bad pack
  3181.                                  /* -1 since C packs are 0 based.
  3182. See: ReindexXBsrc
  3183. ~ReindexXBsrc
  3184. Func: ReindexXB        Pack: AccessPack         Func:  67/High-level
  3185. struct AccessPack AP[3];   /* array of 3 access packs, 1 for each index file
  3186.                            /* keyBuff and recBuff previously defined
  3187. for (i=0,i<3,i++) {        /* 3=number of related indexes to maintain
  3188.    AP[i].func = REINDEXB;
  3189.    AP[i].handle = indexHandle[i]; /* each index file's handle
  3190.    AP[i].nextPtr = &AP[i+1];    /* point to NEXT access pack
  3191. AP[2].nextPtr = NULL;           /* reset last access pack to end-link value
  3192. rstat = BULLET(&AP);
  3193. if (rstat !=0) {
  3194.    trueerror = AP[rstat-1].stat;  /* returned rstat is array index of bad pack
  3195.                                   /* -1 since C packs are 0 based.
  3196. See: LockXBsrc
  3197. ~LockXBsrc
  3198. Func: LockXB           Pack: AccessPack         Func:  80/Network
  3199. struct AccessPack AP[3];   /* array of 3 access packs, 1 for each index file
  3200. for (i=0,i<3,i++) {        /* 3=number of related indexes to maintain
  3201.    AP[i].func = LOCKXB;
  3202.    AP[i].handle = indexHandle[i]; /* each index file's handle
  3203.    AP[i].nextPtr = &AP[i+1];    /* point to NEXT access pack
  3204. AP[2].nextPtr = NULL;           /* reset last access pack to end-link value
  3205. rstat = BULLET(&AP);
  3206. if (rstat > 3) {                /* if rstat > 3 (> number of packs) then the...
  3207.    trueError = AP[2].stat;      /* ...lock failed on the data file
  3208. else                            /* and the error code is in the last pack
  3209.    if (rstat !=0) {
  3210.       trueError = AP[rstat-1].stat  /*...lock failed on index file # rstat
  3211.                                     /* -1 since C packs are 0 based.
  3212. The Lock routines use a different method to identify the bad pack when the   
  3213. failure was caused by the data file. See above.                              
  3214. See: UnlockXBsrc
  3215. ~UnlockXBsrc
  3216. Func: UnlockXB         Pack: AccessPack         Func:  81/Network
  3217. struct AccessPack AP[3];   /* array of 3 access packs, 1 for each index file
  3218. for (i=0,i<3,i++) {        /* 3=number of related indexes to maintain
  3219.    AP[i].func = UNLOCKXB;
  3220.    AP[i].handle = indexHandle[i]; /* each index file's handle
  3221.    AP[i].nextPtr = &AP[i+1];    /* point to NEXT access pack
  3222. AP[2].nextPtr = NULL;           /* reset last access pack to end-link value
  3223. rstat = BULLET(&AP);
  3224. if (rstat > 3) {                /* if rstat > 3 (> number of packs) then the...
  3225.    trueError = AP[2].stat;      /* ...unlock failed on the data file
  3226. else                            /* and the error code is in the last pack
  3227.    if (rstat !=0) {
  3228.       trueError = AP[rstat-1].stat  /*...unlock failed on index file # rstat
  3229.                                     /* -1 since C packs are 0 based.
  3230. The Lock routines use a different method to identify the bad pack when the   
  3231. failure was caused by the data file. See above.                              
  3232. See: LockKeyXBsrc
  3233. ~LockKeyXBsrc
  3234. Func: LockKeyXB        Pack: AccessPack         Func:  82/Network
  3235. struct AccessPack AP[3];   /* array of 3 access packs, 1 for each index file
  3236. for (i=0,i<3,i++) {        /* 3=number of related indexes to maintain
  3237.    AP[i].func = LOCKKEYXB;
  3238.    AP[i].handle = indexHandle[i]; /* each index file's handle
  3239.    AP[i].nextPtr = &AP[i+1];    /* point to NEXT access pack
  3240. AP[2].nextPtr = NULL;           /* reset last access pack to end-link value
  3241. rstat = BULLET(&AP);
  3242. if (rstat !=0) {
  3243.    trueError = AP[rstat-1].stat  /*...lock failed on index file # rstat
  3244.                                  /* -1 since C packs are 0 based.
  3245.                          /*--if rstat > packs (3) then failed on last internal
  3246.                          /*--ReadKHXB...This is EXTREMELY unlikely
  3247. See: UnlockKeyXBsrc
  3248. ~UnlockKeyXBsrc
  3249. Func: UnlockKeyXB      Pack: AccessPack         Func:  83/Network
  3250. struct AccessPack AP[3];   /* array of 3 access packs, 1 for each index file
  3251. for (i=0,i<3,i++) {        /* 3=number of related indexes to maintain
  3252.    AP[i].func = UNLOCKKEYXB;
  3253.    AP[i].handle = indexHandle[i]; /* each index file's handle
  3254.    AP[i].nextPtr = &AP[i+1];    /* point to NEXT access pack
  3255. AP[2].nextPtr = NULL:           /* reset last access pack to end-link value
  3256. rstat = BULLET(&AP);
  3257. if (rstat !=0) {
  3258.    trueError = AP[rstat-1].stat  /*...lock failed on index file # rstat
  3259.                                  /* -1 since C packs are 0 based.
  3260. See: LockDataXBsrc
  3261. ~LockDataXBsrc
  3262. Func: LockDataXB       Pack: AccessPack         Func:  84/Network
  3263. struct AccessPack AP;
  3264. AP.func = LOCKDATAXB;         /* defined in BULLET.H
  3265. AP.handle = dataHandle;       /* handle of data file to lock
  3266. AP.recNo = 0L;                /* =0 to lock all or, set to actual record number
  3267. rstat = BULLET(&AP);          /*    to lock as in AP.recNo = lockThisRec
  3268. if (rstat !=0) ... /* error
  3269. See: UnlockDataXBsrc
  3270. ~UnlockDataXBsrc
  3271. Func: UnlockDataXB     Pack: AccessPack         Func:  85/Network
  3272. struct AccessPack AP;
  3273. AP.func = UNLOCKDATAXB;       /* defined in BULLET.H
  3274. AP.handle = dataHandle;       /* handle of data file to unlock
  3275. AP.recNo = 0L;                /* =0 to unlock all or, set to actual record num
  3276. rstat = BULLET(&AP);          /*    to unlock as in AP.recNo = lockThisRec
  3277. if (rstat !=0) ... /* error
  3278.                               /* note: you cannot unlock parts of a file with
  3279.                               /* 1 single unlock (where AP.recNo=0). Instead,
  3280.                               /* you must unlock each record individually--
  3281.                               /* that is, if you made any single-record locks
  3282. See: DriveRemoteXBsrc
  3283. ~DriveRemoteXBsrc
  3284. Func: DriveRemoteXB    Pack: RemotePack         Func:  86/Network
  3285. struct RemotePack RP;
  3286. RP.func = DRIVEREMOTEXB;      /* defined in BULLET.H
  3287. RP.handle = drive2check;      /* drive to check (0=default, 1=A:,2=B:,3=C:...)
  3288. rstat = BULLET(&RP);
  3289. if (rstat==0) {
  3290.   /* RP.isRemote set to 0 if drive local, 1 if remote
  3291.   /* RP.flags set to DX register as returned by DOS
  3292.   /* RP.isShare set to 0 if SHARE.EXE is not loaded, non-zero SHARE installed
  3293.   /* error  (like invalid drive)
  3294. See: FileRemoteXBsrc
  3295. ~FileRemoteXBsrc
  3296. Func: FileRemoteXB     Pack: RemotePack         Func:  87/Network
  3297. struct RemotePack RP;
  3298. RP.func = FILEREMOTEXB;       /* defined in BULLET.H
  3299. RP.handle = fileHandle;       /* file handle to check
  3300. rstat = BULLET(&RP);
  3301. if (rstat==0) {
  3302.    /* RP.isRemote set to 0 if file local, 1 if remote
  3303.    /* RP.flags set to DX register as returned by DOS
  3304.    /* RP.isShare set to 0 if SHARE.EXE is not loaded, non-zero SHARE installed
  3305.    /* error  (like invalid handle)
  3306. See: SetRetriesXBsrc
  3307. ~SetRetriesXBsrc
  3308. Func: SetRetriesXB     Pack: SetRetriesPack     Func:  88/Network
  3309. struct SetRetriesPack SRP;
  3310. SRP.func = SETRETRIESXB;
  3311. SRP.mode = 1;            /* 1=set to user values, 0=set DOS default
  3312. SRP.pause = 5000;        /* do 5,000 loops between retries
  3313. SRP.retries = 5;         /* try 5 times before giving up with error
  3314. rstat = BULLET(&SRP);
  3315. if (rstat !=0) ... /* error  (this routine is probably a waste of time)
  3316. See: DeleteFileDOSsrc
  3317. ~DeleteFileDOSsrc
  3318. Func: DeleteFileDOS    Pack: DOSFilePack        Func: 100/DOS
  3319. struct DosFilePack DFP;
  3320. DFP.func = DELETEFILEDOS;       /* defined in BULLET.H
  3321. DFP.filenamePtr = filename;
  3322. rstat = BULLET(&DFP);
  3323. if (rstat !=0) ... /* error
  3324. See: RenameFileDOSsrc
  3325. ~RenameFileDOSsrc
  3326. Func: RenameFileDOS    Pack: DOSFilePack        Func: 101/DOS
  3327. struct DosFilePack DFP;
  3328. DFP.func = RENAMEFILEDOS;       /* defined in BULLET.H
  3329. DFP.filenamePtr = orgFilename;
  3330. DFP.newNamePtr = newFilename;
  3331. rstat = BULLET(&DFP);
  3332. if (rstat !=0) ... /* error
  3333. See: CreateFileDOSsrc
  3334. ~CreateFileDOSsrc
  3335. Func: CreateFileDOS    Pack: DosFilePack        Func: 102/DOS
  3336. struct DosFilePack DFP;
  3337. DFP.func = CREATEFILEDOS;       /* defined in BULLET.H
  3338. DFP.filenamePtr = filename;
  3339. DFP.attr = 0;                   /* normal file directory attribute
  3340. rstat = BULLET(&DFP);
  3341. if (rstat !=0) ... /* error
  3342. See: AccessFileDOSsrc
  3343. ~AccessFileDOSsrc
  3344. Func: AccessFileDOS    Pack: DosFilePack        Func: 103/DOS
  3345. struct DosFilePack DFP;
  3346. DFP.func = ACCESSFILEDOS;       /* defined in BULLET.H
  3347. DFP.filenamePtr = filename;
  3348. DFP.asMode = 0x42;              /* attempt R/W DENY NONE access
  3349. rstat = BULLET(&DFP);
  3350. if (rstat !=0) ... /* error
  3351. See: OpenFileDOSsrc
  3352. ~OpenFileDOSsrc
  3353. Func: OpenFileDOS      Pack: DosFilePack        Func: 104/DOS
  3354. struct DosFilePack DFP;
  3355. DFP.func = OPENFILEDOS;         /* defined in BULLET.H
  3356. DFP.filenamePtr = filename;
  3357. DFP.asMode = 0x42;              /* open in R/W DENY NONE access
  3358. rstat = BULLET(&DFP);
  3359. if (rstat !=0) ... /* error else DFP.handle set to handle of open file
  3360. See: SeekFileDOSsrc
  3361. ~SeekFileDOSsrc
  3362. Func: SeekFileDOS      Pack: DosFilePack        Func: 105/DOS
  3363. struct DosFilePack DFP;
  3364. DFP.func = SEEKFILEDOS;         /* defined in BULLET.H
  3365. DFP.handle = handle;
  3366. DFP.seekoffset = 0L;            /* position 0 relative EOF (get length of file)
  3367. DFP.method = 2;                 /* seek from END of file
  3368. rstat = BULLET(&DFP);
  3369. if (rstat==0) {
  3370.    /* DFP.SeekOffset set to absolute current offset
  3371.    /* --in this case, the DFP.seekoffset equals then length of the file
  3372.    /* error
  3373. See: ReadFileDOSsrc
  3374. ~ReadFileDOSsrc
  3375. Func: ReadFileDOS      Pack: DosFilePack        Func: 106/DOS
  3376. struct DosFilePack DFP;
  3377. DFP.func = READFILEDOS;         /* defined in BULLET.H
  3378. DFP.handle = handle;
  3379. DFP.bytes = bytes2read;         /* 16-bit value, in this case 512 since that's
  3380. DFP.bufferPtr = dosBuff;        /* the size of dosbuff
  3381. rstat = BULLET(&DFP);
  3382. if (rstat==0) {
  3383.    if (DFP.bytes != bytes2read) { /* check if EOF processed
  3384.       /* hit EOF before reading all 512 bytes
  3385.    else
  3386.       /* ReadBuff filled with 512 bytes of data read from the current disk pos
  3387.       /* disk position moved to the last byte read + 1
  3388.    /* error
  3389. See: ExpandFileDOSsrc
  3390. ~ExpandFileDOSsrc
  3391. Func: ExpandFileDOS    Pack: DosFilePack        Func: 107/DOS
  3392. struct DosFilePack DFP;
  3393. DFP.func = EXPANDFILEDOS;       /* defined in BULLET.H
  3394. DFP.handle = handle;
  3395. DFP.seekOffset = bytes2expandby;
  3396. rstat = BULLET(&DFP);
  3397. if (rstat==0) {
  3398.    /* file expanded by number of bytes specified
  3399.    /* error
  3400. See: WriteFileDOSsrc
  3401. ~WriteFileDOSsrc
  3402. Func: WriteFileDOS     Pack: DosFilePack        Func: 108/DOS
  3403. struct DosFilePack DFP;
  3404. DFP.func = WRITEFILEDOS;        /* defined in BULLET.H
  3405. DFP.handle = handle;
  3406. DFP.bytes = bytes2write;        /* 16-bit value, in this case 512 since that's
  3407. DFP.buffPtr = dosBuff;          /* the size of dosbuff
  3408. rstat = BULLET(&DFP);
  3409. if (rstat=0xFFFE)               /* -2 that is
  3410.    /* disk full
  3411.    if (rstat !=0) ... /* error
  3412. Unlike ReadFileDOS, if the number of bytes actually written does not equal
  3413. bytes2write, the WriteFileDOS routine returns a DISK FULL error code (-2).
  3414. See: CloseFileDOSsrc
  3415. ~CloseFileDOSsrc
  3416. Func: CloseFileDOS     Pack: DosFilePack        Func: 109/DOS
  3417. struct DosFilePack DFP;
  3418. DFP.func = CLOSEFILEDOS;        /* defined in BULLET.H
  3419. DFP.handle =handle2close;
  3420. rstat = BULLET(&DFP);
  3421. if (rstat !=0) ... /* error
  3422. See: MakeDirDOSsrc
  3423. ~MakeDirDOSsrc
  3424. Func: MakeDirDOS       Pack: DosFilePack        Func: 110/DOS
  3425. struct DosFilePack DFP;
  3426. DFP.func = MAKEDIRDOS;          /* defined in BULLET.H
  3427. DFP.filenamePtr = newDirectoryName;
  3428. rstat = BULLET(&DFP);
  3429. if (rstat !=0) ... /* error
  3430. See: DeleteFileDOSsrc
  3431.